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.

Create one on the console's Tokens page. The group only selects the price tier for text models; video models do not go through it, so leave it on the default auto. Every key can call all of the video models listed here. Pricing is calculated per your account's discount, and the actual amount is whatever /estimate returns for your request — the same model can show a different amount for different customers.

🔴 The IP allow-list on the key is enforced on video endpoints: requests from unlisted IPs return 403 ip_not_allowed. Leave it empty if your egress IP is not fixed. The separate "allowed models" list does not apply to video endpoints.

The response's status starts as queued (that state can be very brief — seeing running already in the submit response is normal), 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 — download and save it promptly; do not rely on it staying reachable long-term. The actual expiry is whatever expires_at in the same response says (it varies by which upstream channel the model runs on — most are about 24 hours; don't hard-code that number).

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.

Last updated: 2026-09-27

02Reference images

🔴 When submitting reference images via the API, provide publicly accessible URLs in image_urls.

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: this platform's upload pre-check rejects any image whose width × height exceeds 36 million pixels (this value is the real rejection threshold observed in production from the current supply channel on 2026-08-18; other supply channels' generation-time upstream limit may differ — the error returned at generation time is authoritative). A typical phone photo at 6048×8064 (about 49 million pixels) exceeds it. An oversized image makes the job fail, and the hold is refunded automatically.

Base64: as in the engine's official API, images / audio can be sent inline as data:image/<format>;base64,… / data:audio/<format>;base64,… (lowercase format; images jpeg, png, webp, bmp, tiff, gif, heic, heif, each under 30 MB; audio wav, mp3, each at most 15 MB; whole request body at most 64 MB). Job details show a link generated by the platform. A wrong format or size returns invalid_inline_media with no charge. Reference videos do not accept Base64. For large files, uploading first (or using the asset library) and passing a link is recommended.

⚠️ Per-request reference limits depend on the model: Seedance 2.0 series — up to 9 reference images, 3 reference videos and 3 reference audio clips; Seedance 2.5 — up to 30 reference images, 10 reference videos and 10 reference audio clips.

Last updated: 2026-09-27

03Asset library: the real-person channel

Currently applies to Seedance 2.0 and Seedance 2.5: these two 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 the channel for referencing real people: register the likeness as an asset first, then reference it in your generation request. Whether other models apply the same moderation depends on the actual error code your generation request gets back (a model that doesn't trigger this check will not return input_image_real_person).

Whenever a Seedance 2.0 or Seedance 2.5 reference image contains a real human face. Reference assets containing real faces must be registered through the asset library; direct image URLs with faces are rejected by content moderation.

• Get a public image or video URL (your own link, or one from the upload endpoint)
• Call the create-asset endpoint with that link and a name (add "kind": "video" for a video asset, "kind": "audio" for an audio asset) → get back an asset ID — video and audio assets accept public direct-download links only; there is no upload endpoint for them. Whether video/audio kinds are supported depends on the current asset-library channel: unsupported kinds return asset_kind_unsupported (400, no charge) — in that case pass a public direct link in the generation request instead of going through the asset library
• Put asset://<asset_id> in the generation request's image_urls (or video_urls for a video asset)

⚠️ After creating an asset there is a brief processing window (usually under ten seconds) before it can be used for generation. Take the id from the create response and query that one asset by id (GET /videos/v1/videos/assets/<id>), polling until status is Active before submitting a generation request, rather than guessing a fixed wait time.

• Register all the images together (one create call each; no need to wait for the previous one to become ready) and keep each id
• Poll each one by id every 2–3 seconds — the address is:
  GET https://tryaiapi.com/videos/v1/videos/assets/<id> (curl example below)
• status is Active → that image is ready to submit
• Failed → register a different image, do not retry the same one
• Put an overall cap of 120 seconds on the whole batch and treat anything beyond it as failed. Most are ready within seconds and a few take longer, so within those 120 seconds, don't mark one as failed just because it is slow

🔴 The poll exit condition must cover both terminal states: Active (processing finished — ready to submit) and Failed (processing failed; change the image).

Use the id from the create response in the path; the asset_id works too. The fields are exactly the same as one item of the list endpoint. An id that is not yours, does not exist, or was deleted returns 404.
(Optional) Adding ?model=<model name> returns one extra boolean field, usable, saying whether this asset can be used under that model; you only need it when you switch back and forth between models. Without ?model=, usable is null.

🔴 The list endpoint is for managing assets — do not poll status with it; poll with the single-asset endpoint above.

⚠️ Failed currently carries no reason; the most common cause is an image that is too small, so use normally sized photographs. Treat Failed as "register a different image" rather than retrying the same one.

Asset status: Processing → Active (processing finished) / Failed (processing failed).
⚠️ In the example above status is still Processing, so this response cannot be submitted straight to generation — take the id from it, poll by id, and submit once status is Active. doubao-seedance-2.0 / doubao-seedance-2.0-fast require waiting until processing finishes; MiniMax-H3 is the exception — an asset can be referenced right after registration, regardless of this status.

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:

Last updated: 2026-09-27

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 spaced form @图片 1 is accepted too) — 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. Only Seedance 2.0 and Seedance 2.5 currently support this @ syntax. MiniMax-H3 does not parse it: distinguish multiple reference images by their order in image_urls and each item's role field (see "Reference images") — you cannot bind a character to a name via @ in the prompt.

⚠️ The API only parses positional syntax such as @图片1, not arbitrary names. A name is treated as plain prompt text and the person binding will not take effect; map names to @图片N in your own application before submitting.

⇒ 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.

Last updated: 2026-09-27

05API reference

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

Error envelope (uniform across the REST endpoints in this section and the Ark-compatible 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 exactly one image and no role, this is treated as first-frame image-to-video.
• 🔴 With two or more images (outside first-and-last-frames mode), any image without a role is treated as a reference image (reference_image); images where you set role yourself follow what you set. Applies to Seedance 2.0 and Seedance 2.5.
• Single-image exception: outside first-and-last-frames mode, doubao-seedance-2.5 treats even a single image as a reference image (reference-to-video).
• A single image without a role, sent together with a reference video or reference audio, is treated as a reference image.
• 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

video_urls / audio_urls take plain URL strings only; you do not need to write a role (on the Ark-format endpoint you may also write these two fixed roles on video_url / audio_url items, as in the official examples). All three fields accept asset:// references, as long as the asset kind matches the field (image → image_urls, video → video_urls, audio → audio_urls).

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; the body is not diffed. Use a new key for each new job.

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, the result is still being confirmed: the charge has not been settled yet, so do not resubmit.

Responds with { items: [...], total, page, page_size, fx_cny_per_usd }, sorted newest-first by submission time (not adjustable). fx_cny_per_usd is the platform's current display USD→CNY rate, for display conversion only; billing is in USD.

Same filter parameters as 5.4. Returns total_jobs / completed_jobs / failed_jobs / in_flight_jobs / total_cost (completed jobs only) / avg_duration_ms / fx_cny_per_usd (display rate, same as 5.4).

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.

Header row (column names map 1:1 to the job object fields in 5.3): job_id, status, model, token_name, cost_final, cost_pending, duration_ms, created_at, completed_at, video_url, platform_video_url, error_code, error_detail, cost_final_cny (display only: cost_final x fx_cny_per_usd, converted at the current display FX), fx_cny_per_usd.

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

The response includes id (for querying and deletion), ref (shaped like asset://xxx, placed directly into image_urls), and status (Processing / Active / Failed). Only Active assets can be used for generation (exception: MiniMax-H3 — an asset can be referenced right after registration, regardless of this status).

List assets GET /videos/v1/videos/assets
Returns { assets: [...] }.
🔴 This endpoint is for managing assets — do not poll status with it; poll with "Get one asset" below.

Get one asset GET /videos/v1/videos/assets/<id>
Returns just this one asset from your library, with the same fields as a list item (id, status, …); <id> may be the id or the asset_id from the create response. Anything that is not yours, does not exist, or was deleted returns 404. After registering, poll by id with this endpoint (every 2–3 seconds): submit once status is Active, and register a different image on Failed — no need to fetch the whole list.
(Optional) When switching between models, add ?model=<model name> so usable reports true/false (without it, or with an unknown model name, it is null).

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 image upload endpoint that turns a local file into a usable URL. An API integration usually does not need it: supply your own public URL instead (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 / bmp / tiff); the response includes url. Images only: there is no upload endpoint for video assets or reference videos — videos must be supplied as publicly downloadable links (mp4 / mov); the video workbench also takes a pasted link, not a local file.

If you already use the Volcano Ark native format, you can connect directly to POST /videos/api/v3/contents/generations/tasks. The table lists only what differs:

Everything else — request format, error format, status values, parameter semantics — matches the official API; which model each parameter applies to is in 5.1. Inline prompt parameters (--rs / --dur, etc.) are parsed into the matching fields, and disagreeing with the top-level field returns 400; for a final video from a draft, draft_task.id is this platform's draft task ID.

Last updated: 2026-09-28

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.

Last updated: 2026-09-28

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.

Isolation is scoped at the account level: every key issued under one account is the same tenant to this platform. 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 library is account-level — all of your users share one library
• 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.

Different customers are isolated from each other: accounts cannot see each other; you cannot see another customer's assets.

Last updated: 2026-09-24

08Quotas & limits

⚠️ Result links expire: by default only the generation engine's own direct link is provided — its actual validity is whatever expires_at in the response says (varies by which upstream channel the model runs on; most are 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 is available on the Ark-compatible endpoint for in-progress tasks when the current supply channel supports cancellation: on success the hold is refunded in full; if the provider no longer accepts cancellation, or the current channel doesn't support it, it returns 400; a task still queued on this platform and not yet submitted to the provider also returns 400. Finished tasks can have their record deleted (see 5.9 "Ark-compatible endpoint: differences from Ark native"). Failed and timed-out jobs are refunded automatically.

Last updated: 2026-09-28

09Integration FAQ

Last updated: 2026-09-27