BeatAPIEcommerce VideoWorkflow API

Ecommerce Video

Create an Ecommerce Video workflow task from product images and an explicit output duration. If an input is local, [upload a local input](/quick-guide#upload-an-input-file) and use the returned `data.url`. Save `data.id`, [poll the Task](/quick-guide#get-task-status), and follow the [error and retry policy](/quick-guide#errors-and-retry-policy).

Authentication

AuthorizationBearer

Send your API key as Authorization: Bearer <BEATAPI_API_KEY>.

Headers

Idempotency-KeystringOptional

Optional retry key. Reusing the same key with the same request body returns the accepted task; reusing it with a different body returns 409 idempotency_conflict.

Request

This endpoint expects an object.
imageslist of stringsRequired

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.

durationintegerRequired10-60

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

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

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

Allowed values:
languageenumOptional

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

Allowed values:

Response

Task accepted
dataobject
Accepted or current BeatAPI task state.

Errors

400
Bad Request Error
401
Unauthorized Error
402
Payment Required Error
409
Conflict Error
429
Too Many Requests Error