> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.beatapi.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.beatapi.io/_mcp/server. # Ecommerce Video POST https://api.beatapi.io/v1/ecommerce-video/tasks Content-Type: application/json 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). Reference: https://docs.beatapi.io/api-reference/workflow-api/ecommerce-video ## Authentication - `Authorization` header (bearer token, required) — Send your API key as `Authorization: Bearer `. ## Request ### Headers - `Idempotency-Key` (string, optional) — 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`. ### Body (application/json) This endpoint expects an object. - `images` (list of 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`. - `duration` (integer, required) — Required target output duration in seconds and the basis for USD calculation. Allowed range is 10-60 seconds. - `prompt` (string, optional) — Optional creative direction, audience, product benefit, offer, tone, scenes, or call to action. Maximum 2000 characters. - `aspect_ratio` (enum, 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. - Allowed values: `16:9`, `9:16`, `1:1` - `language` (enum, optional) — Dialogue and narration language. Use `en` for English or `zh` for Chinese; set explicitly when the prompt contains mixed languages. - Allowed values: `en`, `zh` ## Response ### 201 Task accepted - `data` (Task, required) — Accepted or current BeatAPI task state. ## Errors ### 400 Bad Request Error Malformed JSON or a field, value or combination this endpoint does not accept (`bad_request`; the message names the field), or input refused by moderation (`content_policy_violation`). Not retryable unchanged. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 401 Unauthorized Error No API key (`missing_api_key`), or a key that is wrong, expired, disabled or exhausted (`invalid_api_key`; the message says which). Send it as `Authorization: Bearer `; the key works with or without the `sk-` prefix. Not retryable. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 402 Payment Required Error Insufficient balance (`insufficient_credits`). The account balance is zero or below the price of this request. Top up, then send it again; not retryable before that. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 403 Forbidden Error The key or account is not permitted to make this call (`forbidden`), for example a model that is not available on free credit (a top-up unlocks it), a request from outside the key's IP allowlist, or a model outside the key's group. Not retryable. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 409 Conflict Error The `Idempotency-Key` was already used with a different request body, or the first request with it is still being processed (`idempotency_conflict`). Not retryable unchanged. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 429 Too Many Requests Error Too many tasks processing at once (`user_concurrency_exceeded`) or too many requests (`rate_limit_exceeded`). Retryable once a processing task finishes, or after `Retry-After` seconds. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 500 Internal Server Error Unexpected internal error (`internal_error`). Retryable; keep `request_id` for support if it persists. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ### 503 Service Unavailable Error The request could not be completed (`processing_unavailable`, `processing_timeout`, `processing_failed` or `result_transfer_failed`). Nothing was charged. Retryable with backoff; `Retry-After` is sent when the wait is known. BeatAPI does not answer 502 or 504. - `error` (ErrorError, required) — Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. ## Types ### Task - `id` (string, required) — Stable BeatAPI task ID used for polling and support. - `object` (enum, required) — Object discriminator; always `task`. - Allowed values: `task` - `task_kind` (enum, required) — Public task family that determines which capability fields are present. `data` is a data capability run as a task (`data:web.research`), polled through `POST /v1/capabilities/run`. - Allowed values: `workflow`, `effect`, `image`, `video`, `data` - `capability_id` (string, required) — Stable BeatAPI workflow, Effect, generation model, or data capability ID (such as `web.research`) selected when the task was accepted. - `capability_version` (integer, required, nullable) — Immutable capability version used by this task. Legacy workflow rows are returned as version 1. - `status` (enum, required) — Current task lifecycle status. Stop polling at `succeeded` or `failed`; Music Video can also require manual action. - Allowed values: `queued`, `processing`, `storyboard_ready`, `requires_action`, `editing`, `composing`, `succeeded`, `failed` - `stage` (enum, required) — Current processing stage, exposed separately so workflow progress can be tracked. - Allowed values: `queued`, `processing`, `storyboard_ready`, `requires_action`, `editing`, `composing`, `succeeded`, `failed` - `created_at` (integer, required) — Unix timestamp when BeatAPI accepted the task. - `updated_at` (integer, required) — Unix timestamp of the latest task update. - `completed_at` (integer, required, nullable) — Terminal Unix timestamp, or null while work is in progress. - `output` (TaskOutput, required, nullable) — Output is null until the task succeeds. - `usage` (TaskUsage, required) — USD reservation, settlement, refund, and optional billable duration for this task. - `request_id` (string, required) — Correlation ID to retain for logs and BeatAPI support. - `error_code` (string, required, nullable) — Machine-readable terminal failure code, or null when no task failure is recorded. - `error_message` (string, required, nullable) — Human-readable terminal failure detail, or null when no task failure is recorded. - `workflow` (enum, optional) — Present for workflow tasks; identifies the selected BeatAPI workflow. - Allowed values: `music-video`, `ecommerce-video`, `video-analysis` - `effect_id` (string, optional) — Present for Effect tasks; stable selected Effect ID. - `effect_version` (integer, optional) — Present for Effect tasks; immutable Effect version used for processing. - `media_type` (enum, optional) — Present when task_kind is image or video. - Allowed values: `image`, `video` - `model` (string, optional) — Stable BeatAPI model alias. It is independent from internal execution routing. - `storyboard` (Storyboard, optional) — Music Video storyboard metadata when available. - `poll_after_seconds` (integer, optional) — Present while the task is running: how long to wait before the next status call (5 for images, 8 for video and Effects, 10 for workflows and data tasks). Absent on a terminal task. - `typical_seconds` (TaskTypicalSeconds, optional) — Present while the task is running, when enough recent finishes exist: how long this task's model recently took from accepted to succeeded, measured on this gateway. Past `p90` with no change the task is running long; there is no ETA beyond that. - `retryable` (boolean, optional) — Present on a failed task: whether resubmitting could succeed. True when the task failed on our side or timed out (a failed task is not charged); false when it was refused for content or bad input. Same code-to-retryable rule as the error envelope. ### ErrorError Structured BeatAPI error. Use `code` (or `retryable`) for program logic and retain `request_id` for support. - `code` (enum, required) — Stable machine-readable error code. `unauthorized` is the deprecated name for a 401; since 2026-09-29 a 401 is `missing_api_key` or `invalid_api_key`. Treat a legacy `unauthorized` like `invalid_api_key`. - Allowed values: `bad_request`, `missing_api_key`, `invalid_api_key`, `unauthorized`, `forbidden`, `not_found`, `insufficient_credits`, `idempotency_conflict`, `user_concurrency_exceeded`, `rate_limit_exceeded`, `content_policy_violation`, `processing_unavailable`, `processing_failed`, `processing_timeout`, `result_transfer_failed`, `invalid_signature`, `realtime_disabled`, `realtime_capacity_unavailable`, `realtime_session_expired`, `origin_not_allowed`, `invalid_client_secret`, `transport_not_allowed`, `internal_error` - `message` (string, required) — English sentence that states the cause; for `bad_request` it names the field. Written for people and logs, not for parsing. - `retryable` (boolean, required) — Whether making the same call again could succeed. Present on every error; branch on it instead of the status code. True for 429, 500 and 503 (rate_limit_exceeded, user_concurrency_exceeded, internal_error, processing_unavailable, processing_timeout, processing_failed, result_transfer_failed, realtime_capacity_unavailable). False for a request, key or balance that must change first (bad_request, content_policy_violation, missing_api_key, invalid_api_key, insufficient_credits, forbidden, not_found, idempotency_conflict, realtime_disabled and the other realtime credential codes). - `request_id` (string, required) — Correlation ID to retain for BeatAPI support. - `retry_after_seconds` (integer, optional) — Seconds to wait before retrying. Present on every 429, and on a 503 when the wait is known; the same value is sent in the `Retry-After` header. - `docs` (string, optional) — The public Skill page that says what to do about an error. Present on errors answered by the capability endpoints (`/v1/capabilities/search`, `/v1/capabilities/inspect`, `/v1/capabilities/run`); absent on every other endpoint. ### TaskOutput Output is null until the task succeeds. ### TaskUsage - `credits_reserved` (double, required) — USD amount reserved for this task. The compatibility field name is retained; 1 Credit equals $1 USD. - `credits_charged` (double, required) — USD amount charged when the task or operation is accepted. - `credits_settled` (double, required) — USD amount settled after successful work. - `credits_refunded` (double, required) — USD amount refunded after failed eligible work. - `billable_duration_seconds` (integer, optional) — Server-detected or request-declared billable duration used for USD calculation. ### Storyboard - `shots` (list of StoryboardShot, required) — Ordered Music Video storyboard shots. The array may be empty before storyboard generation completes. ### TaskTypicalSeconds Present while the task is running, when enough recent finishes exist: how long this task's model recently took from accepted to succeeded, measured on this gateway. Past `p90` with no change the task is running long; there is no ETA beyond that. - `p50` (integer, required) — Median seconds. - `p90` (integer, required) — Ninetieth-percentile seconds. - `samples` (integer, required) — Finished tasks the figures rest on. - `window` (string, required) — The window measured, such as `7d`. ### TaskOutput0 - `media` (list of TaskOutputOneOf0MediaItems, required) — BeatAPI-hosted result assets. - `r2_url` (string, required, deprecated) — Deprecated — read media[0].url. The primary asset's URL again (the video, else the first image), the same value as that media[].url, kept only for clients that read one URL. ### TaskOutput1 - `text` (string, required) — Completed video analysis text. - `usage` (TaskOutputOneOf1Usage, required) — Measured token usage used for final USD settlement. - `finish_reason` (string, required, nullable) — Why the model stopped generating. ### TaskOutput2 A data task's result: the capability's own result object, such as `web.research` with `research_notes` and `sources` (in a view: `items`). - `object` (string, required) — The result type, such as `web.research`. ### StoryboardShot - `id` (string, required) — BeatAPI shot id. Use this id for media retrieval, edit, and compose operations. - `index` (integer, required) — Zero-based shot order in the storyboard. - `status` (enum, required) — Current lifecycle state for this storyboard shot. - Allowed values: `queued`, `processing`, `storyboard_ready`, `requires_action`, `editing`, `composing`, `succeeded`, `failed` - `created_at` (integer, required) — Unix timestamp when the shot record was created. - `updated_at` (integer, required) — Unix timestamp when the shot record last changed. - `duration_seconds` (integer, optional) — Planned or generated shot duration in seconds. - `prompt` (string, optional) — Creative instruction used to generate this shot. - `lyric_text` (string, optional) — Lyric segment aligned with this shot when available. - `media` (StoryboardShotMedia, optional) — Present only after the shot media has been materialized or after a shot edit finishes. ### TaskOutputOneOf0MediaItems - `type` (enum, required) — Result asset type. - Allowed values: `image`, `video` - `url` (string, required) — BeatAPI-hosted HTTPS result URL. - `mime_type` (string, required) — Result asset MIME type. ### TaskOutputOneOf1Usage Measured token usage used for final USD settlement. - `input_tokens` (integer, required) — Tokens consumed by the prompt and video input. - `output_tokens` (integer, required) — Tokens consumed by visible output and model reasoning. - `total_tokens` (integer, required) — Total measured input and output tokens. ### StoryboardShotMedia Present only after the shot media has been materialized or after a shot edit finishes. - `type` (string, optional) — Hosted media type for the materialized shot. - `url` (string, optional) — BeatAPI-hosted HTTPS URL for the materialized shot. - `mime_type` (string, optional) — MIME type of the hosted shot media. ## Examples **Request** ```json { "images": [ "https://media.beatapi.io/samples/smart-bottle.png" ], "duration": 15, "prompt": "Fast product launch ad for paid social.", "aspect_ratio": "9:16" } ``` **Response** ```json { "data": { "id": "task_p9Lm2", "object": "task", "task_kind": "workflow", "capability_id": "ecommerce-video", "capability_version": 1, "status": "queued", "stage": "queued", "created_at": 1782210000, "updated_at": 1782210000, "completed_at": null, "output": null, "usage": { "credits_reserved": 4.5, "credits_charged": 4.5, "credits_settled": 0, "credits_refunded": 0, "billable_duration_seconds": 15 }, "request_id": "req_def456", "error_code": null, "error_message": null, "workflow": "ecommerce-video" } } ``` **SDK Code** ```python Ecommerce Video import requests url = "https://api.beatapi.io/v1/ecommerce-video/tasks" payload = { "images": ["https://media.beatapi.io/samples/smart-bottle.png"], "duration": 15, "prompt": "Fast product launch ad for paid social.", "aspect_ratio": "9:16" } headers = { "Idempotency-Key": "ecommerce-create-cus_123-01", "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript Ecommerce Video const url = 'https://api.beatapi.io/v1/ecommerce-video/tasks'; const options = { method: 'POST', headers: { 'Idempotency-Key': 'ecommerce-create-cus_123-01', Authorization: 'Bearer ', 'Content-Type': 'application/json' }, body: '{"images":["https://media.beatapi.io/samples/smart-bottle.png"],"duration":15,"prompt":"Fast product launch ad for paid social.","aspect_ratio":"9:16"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Ecommerce Video package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.beatapi.io/v1/ecommerce-video/tasks" payload := strings.NewReader("{\n \"images\": [\n \"https://media.beatapi.io/samples/smart-bottle.png\"\n ],\n \"duration\": 15,\n \"prompt\": \"Fast product launch ad for paid social.\",\n \"aspect_ratio\": \"9:16\"\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Idempotency-Key", "ecommerce-create-cus_123-01") req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Ecommerce Video require 'uri' require 'net/http' url = URI("https://api.beatapi.io/v1/ecommerce-video/tasks") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Idempotency-Key"] = 'ecommerce-create-cus_123-01' request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"images\": [\n \"https://media.beatapi.io/samples/smart-bottle.png\"\n ],\n \"duration\": 15,\n \"prompt\": \"Fast product launch ad for paid social.\",\n \"aspect_ratio\": \"9:16\"\n}" response = http.request(request) puts response.read_body ``` ```java Ecommerce Video import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.beatapi.io/v1/ecommerce-video/tasks") .header("Idempotency-Key", "ecommerce-create-cus_123-01") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"images\": [\n \"https://media.beatapi.io/samples/smart-bottle.png\"\n ],\n \"duration\": 15,\n \"prompt\": \"Fast product launch ad for paid social.\",\n \"aspect_ratio\": \"9:16\"\n}") .asString(); ``` ```php Ecommerce Video request('POST', 'https://api.beatapi.io/v1/ecommerce-video/tasks', [ 'body' => '{ "images": [ "https://media.beatapi.io/samples/smart-bottle.png" ], "duration": 15, "prompt": "Fast product launch ad for paid social.", "aspect_ratio": "9:16" }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', 'Idempotency-Key' => 'ecommerce-create-cus_123-01', ], ]); echo $response->getBody(); ``` ```csharp Ecommerce Video using RestSharp; var client = new RestClient("https://api.beatapi.io/v1/ecommerce-video/tasks"); var request = new RestRequest(Method.POST); request.AddHeader("Idempotency-Key", "ecommerce-create-cus_123-01"); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"images\": [\n \"https://media.beatapi.io/samples/smart-bottle.png\"\n ],\n \"duration\": 15,\n \"prompt\": \"Fast product launch ad for paid social.\",\n \"aspect_ratio\": \"9:16\"\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift Ecommerce Video import Foundation let headers = [ "Idempotency-Key": "ecommerce-create-cus_123-01", "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "images": ["https://media.beatapi.io/samples/smart-bottle.png"], "duration": 15, "prompt": "Fast product launch ad for paid social.", "aspect_ratio": "9:16" ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.beatapi.io/v1/ecommerce-video/tasks")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```