Ecommerce Video

POST https://api.beatapi.io/v1/ecommerce-video/tasks

Create an Ecommerce Video workflow task from product images and an explicit output duration.

Authorization

Authorization   string   required

Send your BeatAPI API key as a Bearer token. Create one on the Dashboard.

Authorization: Bearer <BEATAPI_API_KEY>

Keep permanent API keys on trusted servers. Content-Type: application/json is required for the request body. Idempotency-Key is optional when the endpoint exposes it and is recommended for safe retries with the exact same body.

Request body

images   string[]   required

Primary product or scene image first, followed by up to six additional public HTTPS PNG, JPEG, or WebP product or lifestyle images. Upload local files with POST /v1/files and use the returned data.url.

Count: 1 to 7 items

duration   integer   required

Required target output duration in seconds and the basis for USD calculation. Allowed range is 10-60 seconds.

Range: 10 to 60

prompt   string   optional

Optional creative direction, audience, product benefit, offer, tone, scenes, or call to action. Maximum 2000 characters.

Length: at most 2000 characters

aspect_ratio   enum<string>   optional

Target output placement. Use 16:9 for landscape, 9:16 for vertical social, or 1:1 for square placements; set explicitly for stable layout.

Available options: 16:9, 9:16, 1:1

language   enum<string>   optional

Dialogue and narration language. Use en for English or zh for Chinese; set explicitly when the prompt contains mixed languages.

Available options: en, zh

Response

A successful request returns HTTP 201.

1
{
2
  "data": {
3
    "id": "task_p9Lm2",
4
    "object": "task",
5
    "task_kind": "workflow",
6
    "capability_id": "ecommerce-video",
7
    "capability_version": 1,
8
    "workflow": "ecommerce-video",
9
    "status": "queued",
10
    "stage": "queued",
11
    "created_at": 1782210000,
12
    "updated_at": 1782210000,
13
    "completed_at": null,
14
    "output": null,
15
    "usage": {
16
      "credits_reserved": 4.5,
17
      "credits_charged": 4.5,
18
      "billable_duration_seconds": 15,
19
      "credits_settled": 0,
20
      "credits_refunded": 0
21
    },
22
    "request_id": "req_def456",
23
    "error_code": null,
24
    "error_message": null
25
  }
26
}

Next step

Save data.id from the accepted response and poll GET /v1/tasks/{task_id} every 5–10 seconds until status is succeeded or failed. Read finished assets from data.output.media.

Errors