Video Model API Platform Integration Guide

01Get your first video running in 3 minutes

Want to try it before you write any code? Use your API key in the video workbench to generate a video directly — no code required.

The minimal loop is three steps: submit → poll → download.

⚠️ Generation is asynchronous. Turnaround time varies with the model, duration, and scene complexity. Submission returns a job ID, not a video — poll the response's poll_url to get the result. Do not wait synchronously.

The response's status starts as queued, then moves to running; poll_url is the address you poll next:

The request fields are identical to submission — just swap the path for /generations/estimate. It does not create a job, charge you, or trigger generation.

Take the poll_url from the previous response and request it as-is:

Once status becomes completed, video_url is a direct, downloadable link to the video:

⚠️ video_url expires after about 24 hours — download and save it promptly; do not rely on it staying reachable long-term.

The table above lists the currently available video models; for the complete, real-time list see the model market. Video models are not returned by the text-gateway GET /v1/models endpoint.

02Reference images

🔴 When submitting reference images via the API, provide publicly accessible URLs in image_urls. This matches the generation engine's own upstream requirement — upstream only accepts links, never raw files.

For images containing real people: first create an asset using that URL, then reference it in your generation request as asset://<asset_id> — see "Asset library: the real-person channel" below.

(This platform also offers a separate upload endpoint, used by the video workbench when a user selects a local image; a platform integration built on the API does not need it — see "API reference → 5.8".)

⚠️ Pixel limit: each image's width × height must not exceed 36 million pixels. A typical phone photo at 6048×8064 (about 49 million pixels) will be rejected. When you submit a public URL, this platform does not pre-screen pixels — downscale on your own side, or the failure will only surface at generation time. The upload endpoint does reject oversized files at upload time.

⚠️ Up to 9 reference images per request.

03Asset library: the real-person channel

Models apply content moderation to reference images that contain real people — submitting a raw image link for one will be rejected. The asset library is this platform's compliance channel for that case: register the likeness as an asset first, then reference it in your generation request.

Whenever a reference image contains a real human face. If every video in your product features a real person (store walkthroughs, voiceover hosts, creator appearances), then the asset library isn't optional — it's the only path through.

• Get an image link (your own public URL, or one from the upload endpoint)
• Call the create-asset endpoint with that link and a name → get back an asset ID
• In your generation request's image_urls, write asset://<asset_id>

⚠️ After creating an asset there is a brief processing window before it can be used for generation. Trust the usable field from the list endpoint — poll until usable is true before submitting a generation request, rather than guessing a fixed wait time.

Asset status: Processing → Active (processing finished) / Failed (processing failed).
⚠️ The usable field in this create response is always true. It only means "this asset was created on the current channel" and does not mean it is ready — in the example above status is still Processing.
doubao-seedance-2.0 / -fast require waiting for Active. Use the usable value from the list endpoint with ?model=<model name> — it folds in both "sits on the right channel" and "is ready on that channel", which makes it more accurate than status alone.

When in doubt, call GET /videos/v1/videos/assets/capability?model=<model name> — its enabled field tells you directly whether that model can reference assets.

Take the ref from the previous step (asset://<asset_id>) and place it in image_urls, exactly like a regular image link:

04Naming people & mention syntax

When several reference images appear together, you can tell the prompt "have this person do X" by naming them.

🔴 Over the API you must use the positional mention syntax @图片1, @图片2 — the number matches the order of the image_urls array (starting at 1). These two tokens are a literal, untranslated string the upstream model requires; do not substitute an English phrase for them.

⚠️ The video workbench lets you type a name like @Alex — the API does not. The video workbench rewrites that name into a positional token before it ever reaches the API; the API itself performs no such rewrite, so whatever name you type is treated as plain text and the person binding will not take effect.

⇒ If you want your users to be able to use names, the rewrite has to happen in your own product: maintain a "name → which position this image is" mapping, and rewrite it to @图片N before you submit.

05API reference

Authentication: every endpoint uses Authorization: Bearer <your key>.

Error envelope (uniform across every endpoint):

Please branch on code, not on the message text — copy may change, code is stable.

Each item in image_urls can be:

• A string: a public image URL, or asset://<asset_id>. With no role, this is treated as first-frame image-to-video; exception: doubao-seedance-2.5 automatically adds reference_image outside first-and-last-frames mode (treated as reference-to-video)
• An object: { "url": "...", "role": "reference_image" }, where role may be first_frame / last_frame / reference_image. For multimodal reference, set role to reference_image explicitly

Request header Idempotency-Key (optional, strongly recommended): send the same key on a network retry and it will not create a duplicate job or charge you twice. Submitting again with the same key returns the first job, even if the body changed — it looks like success, but the video is the previous one. Use a new key for a new job. This endpoint does not return 409 when the body differs.

Success response:

Same request fields as 5.1. It does not create a job, charge you, or trigger generation.

Job status values:

⚠️ When you see running with a status_note, we are confirming the result with the generation provider — the charge has not been settled yet; do not resubmit.

Responds with { items: [...], total, page, page_size }, sorted newest-first by submission time (not adjustable).

Same filter parameters as 5.4. Returns total_jobs / completed_jobs / failed_jobs / in_flight_jobs / total_cost (completed jobs only) / avg_duration_ms.

Same filter parameters as 5.4. ⚠️ A single export is capped at 200 rows — for more, page through 5.4 and aggregate on your side.

Create an asset POST /videos/v1/videos/assets

The response includes id (for deletion), ref (shaped like asset://xxx, placed directly into image_urls), and status (Processing / Active / Failed). Only Active assets can be used for generation.

List assets GET /videos/v1/videos/assets?model=<model name>
Returns { assets: [...] }. With model supplied, each item carries usable indicating whether it's usable under that model; without model, usable is null (undetermined — do not treat it as usable).

Delete an asset DELETE /videos/v1/videos/assets/<asset_id>
Removes it from your library. already_retired: true in the response means it was already deleted (repeat calls are safe).

Check capability GET /videos/v1/videos/assets/capability?model=<model name>
Returns enabled (whether that model supports the asset library), upload_max_bytes, and upload_max_pixels. We recommend reading this endpoint at integration time rather than hardcoding these limits in your own code.

This platform provides an upload endpoint used by the video workbench when a user selects a local image — it turns a local file into a usable URL. A platform integration built on the API does not need it: you already hold or can produce your own public URL, which matches upstream's own contract (see "Reference images" above).

POST /videos/v1/videos/uploads, with the raw image bytes as the request body (not a form) — declare the type via Content-Type (image/jpeg / png / webp / gif / heic / heif); the response includes url.

06Error codes

Branch on code, not on the message text.

• 400-class: don't auto-retry — the request itself needs to change.
• 401 / 402 / 404: don't auto-retry.
• 429: exponential backoff.
• 502 / 503 / 504: retryable with backoff, except submission_result_ambiguous — it means we could not confirm whether that job was accepted by the generation provider; retrying blindly risks a duplicate video and a duplicate charge.

07Tenancy & isolation boundaries 🔴 read before integrating

Assets and jobs are scoped to your account, not to an individual API key.

If you only call this API from within your own service and you decide who sees what, none of this affects your users — everything they see is determined entirely by your product. But if you plan to hand off listing, querying, or deleting assets to them (for example, an asset-management panel for your users, or handing them a key directly), read this section first.

The reason: even if you issue different keys to different users, this platform sees all of them as the same tenant. As a result:

• Once you expose "list assets" / "delete assets" to your users, User A can see, and can delete, an asset uploaded by User B
• The asset-count cap is account-level — all of your users share the same quota: up to 100,000 per account
• Usage breakdowns are available at the granularity of a key, at finest

This platform can only see down to your account — it cannot see, or distinguish, which of your users is behind a given call on your product. Who-can-see-whom and what-permissions-they-have among your own users can only be implemented in your own product — this is a layer this platform cannot do for you.

Isolation between different customers (i.e. different accounts) is guaranteed: accounts cannot see each other; you cannot see another customer's assets.

08Quotas & limits

🔴 Asset library capacity is account-level — all of your users share the same quota: up to 100,000 assets per account, which covers the large majority of use cases. If you have a large user base and need a higher cap, contact us to raise it.

⚠️ Result links expire: by default only the generation engine's own direct link is provided (valid for about 24 hours) — download and move it to your own storage promptly; if you need this platform to retain a 7-day copy, contact us to enable it.

⚠️ Cancelling a job is not currently supported.

09Integration FAQ