The wallet is pre-authorized at submit, and billing happens on success only. There is a per-key cap on simultaneous in-flight jobs, and exceeding it returns 429.
i
A model that is published but not currently reachable on this account returns 422published_not_serving rather than retrying automatically. See the errors referencefor what to do next.
Attachments (the content array)
A plain prompt covers text-only generation. To attach an image or video, use content instead, which is an array of typed blocks.
JSON
{
"model": "seedance-2-0",
"content": [
{ "type": "text", "text": "The camera slowly zooms in on the harbor at dawn" },
{ "type": "image_url", "image_url": { "url": "https://example.com/harbor.jpg" }, "role": "first_frame" }
],
"parameters": { "duration": 5, "resolution": "720p" }
}
Send either prompt or content , never both. Each block in content carries a type and, for attachments, a role that tells the model what the attachment is for.
Block type
Fields
Notes
text
text
The prompt text. Exactly one text block per request.
image_url
image_url.url, role
An image attachment. The role determines how the model uses it, as described in the table below.
video_url
video_url.url, role
A video attachment. The role determines how the model uses it, as described in the table below.
The role field on an attachment block tells the model what it is for. Not every model accepts every role, and each model's own page lists the roles it accepts.
Role
Applies to
Meaning
first_frame
image_url
The starting frame for image-to-video generation.
reference_image
image_url
A reference image: likeness, style or subject to carry into the generated clip.
reference_video
video_url
A reference video: motion or style to carry into the generated clip.
The roles a specific model accepts, and how many, are documented on that model's own page. Not every model supports every role.
i
When the request sets audio: true and includes a face as first_frame or reference_image , set likeness_attested: true to confirm permission from that person to make them speak. Silent video and faceless audio need no attestation. Omitting it on a request that needs it returns 422.
Attachments
Every image_url and video_url block is fetched, validated and stored server-side before the job is submitted. An attachment that fails validation returns 400invalid_request_error.
Every model has its own page with real, per-model attachment limits: accepted roles, maximum counts, file types, dimensions and byte ceilings.
Still generating; url is null. The processing state is often brief, and some jobs finish between one poll and the next.
succeeded
Done; url points at the clip (also in the library, with a "via API" badge). Metered once at list price.
failed
Generation failed. A safe, redacted message is shown instead of the raw upstream error. Not billed.
Only the job's owner can read it. A foreign or unknown id returns 404, never a confirming error. Terminal jobs are idempotent.
Billing
Video is priced per second at the model's list rate for the requested resolution and duration, the same rate the composer quotes before submission.
A succeeded job's usage.completionTokens field reports the underlying token count that some vendors bill on, for reference only. It does not determine the price.
i
The wallet is pre-authorized at submit and settled on success; a failed job is never billed.
Errors
The full status/type table is on the shared errors reference. This endpoint carries the most modality-specific errors of the three:
Status
Type
When
400
invalid_request_error
Neither prompt nor content was sent.
422
invalid_request_error
The content array includes a first_frame or reference_image with a face, plus audio: true, and the request did not set likeness_attested: true.
422
published_not_serving
The model is published but this account cannot currently reach it because the SKU is vendor-locked. Please try again later or select another model.
422
model_capability_unsupported
The request is well-formed, but the model cannot honor it: an attachment role, last_frame or reference count the model does not support. See the attachment roles by model.
422
invalid_request_error
The combination of options is individually valid but has no price tier yet. This is a gap in the AI HUB price sheet, not a request error. Please select a different combination.
400
invalid_request_error
An attachment exceeded this model's per-file or total byte ceiling. The model's own page lists its real limits.
429
rate_limit_exceeded
The account already has the maximum number of videos generating at once. See Rate limits for the current cap.
402
insufficient_funds
The wallet balance passed the pre-flight check but could not cover this job's price at submit time. This differs from an empty wallet.
502
upstream_error
The vendor connection failed, timed out, or returned an unrecognized shape. Retry.
The attachment roles each model accepts, and the maximum count where the role is an array. A blank cell means the model refuses that role entirely. Each model's own page lists its byte and dimension ceilings.
