submit_video_generation
Submit a video generation task
Submit an asynchronous video generation task.
Starts a Seedance generation job — text-to-video, image-to-video, or
video-to-video depending on content — and returns a taskId
immediately; the video is produced in the background. Poll
GET /openapi/v2/model/video/tasks/{task_id} with the returned id
until status is terminal to obtain the video URL.
Available to CONTRACT-tier API keys only, and only for models enabled
for the account (GET /openapi/v2/model/video/models; others return 404).
At submit time an upper-bound cost estimate is frozen (held) on the
account's USD wallet; an insufficient balance returns 402 with
X-Usd-Required-* headers and no task is created. The actual cost is
settled against that hold when the task succeeds — whether the success
is observed by your poll or by our background finalizer (polling is not
required for billing) — and the unused part of the hold is released. A
task that fails or expires is not charged.
Request body:
model(string, required):seedance-2.5,seedance-2.0,seedance-2.0-fast, orseedance-2.0-mini.content(array, required, >= 1 item): generation inputs as an OpenAI-style content array. Must include at least one text item{"type": "text", "text": "<prompt>"}. May also include reference media items such as{"type": "image_url", "image_url": {"url": "https://..."}, "role": "reference_image"}(and likewisevideo_url/audio_url), capped at 9 image, 3 video, and 3 audio items on the 2.0 models, or 30 / 10 / 10 onseedance-2.5.roleis one offirst_frame,last_frame,reference_image,reference_video,reference_audio. Reference URLs must be publicly reachable.resolution(string, optional, default720p):480p,720p, or1080p.1080pis only supported byseedance-2.0andseedance-2.5. Also the billing tier.duration(integer, required): output length in seconds, 4-15 on the 2.0 models or 4-30 onseedance-2.5.ratio(string, optional): output aspect ratio —21:9,16:9,4:3,1:1,3:4,9:16, oradaptive.generate_audio(boolean, optional): generate an audio track.watermark(boolean, optional): overlay the provider watermark.service_tier(string, optional):flexfor cheaper offline inference.return_last_frame(boolean, optional): also return the video's last frame onoutput. Any further unrecognized top-level fields are forwarded to the generation provider unchanged.
Response data:
taskId(string): identifier to poll, formattask_video_<id>.status(string): alwayspendingimmediately after submit.
Responses:
200: Successful Response (Success Response) Content-Type: application/json
Example Response:
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}Output Schema:
{
"properties": {
"success": {
"type": "boolean",
"title": "Success",
"description": "Whether the request was successful",
"default": true
},
"data": {
"description": "Response data payload"
},
"error": {
"description": "Error details if request failed"
},
"meta": {
"description": "Metadata for API responses.\n\nCredit fields follow the ADR-0003 parallel-fields strategy (Option 3):\n- `credits_remaining` / `credits_consumed` (int): legacy fields, rounded\n to whole credits, kept for zero-breaking-change to existing SDK clients.\n- `credits_remaining_exact` / `credits_consumed_exact` (float): new\n precision-aware fields for clients that opt in to decimal credits.\n\nSee ADR-0003 decision 5 and the \u00a78 deprecation timeline.\n\nTODO(2026-11, ADR-0003 \u00a78 +6mo): mark `credits_remaining` /\n`credits_consumed` as `deprecated=True` in their Field() definitions\nand announce in customer changelog.\nTODO(2027-05, ADR-0003 \u00a78 +12mo): remove the legacy int fields via a\nmajor-version bump of the OpenAPI surface.",
"properties": {
"requestId": {
"type": "string",
"title": "Requestid",
"description": "Unique request identifier"
},
"timestamp": {
"type": "string",
"title": "Timestamp",
"description": "Response timestamp in ISO 8601 format"
},
"total": {
"title": "Total",
"description": "Total number of records"
},
"page": {
"title": "Page",
"description": "Current page number"
},
"pageSize": {
"title": "Pagesize",
"description": "Number of records per page"
},
"totalPages": {
"title": "Totalpages",
"description": "Total number of pages"
},
"creditsRemaining": {
"title": "Creditsremaining",
"description": "Remaining API credits (rounded to whole credits; see creditsRemainingExact for precise value)"
},
"creditsConsumed": {
"title": "Creditsconsumed",
"description": "Credits consumed by this request (rounded; see creditsConsumedExact for precise value)"
},
"creditsRemainingExact": {
"title": "Creditsremainingexact",
"description": "Remaining API credits, precise to 1 decimal place"
},
"creditsConsumedExact": {
"title": "Creditsconsumedexact",
"description": "Credits consumed by this request, precise to 1 decimal place"
},
"tokensUsage": {
"description": "Provider token-usage block \u2014 populated on terminal video polls only, null on every non-video endpoint. See TokensUsage for its fields."
}
},
"type": "object",
"required": [
"requestId",
"timestamp"
],
"title": "ResponseMeta"
}
},
"type": "object",
"required": [
"meta"
],
"title": "OpenApiResponse[VideoGenerationSubmitData]",
"examples": []
}422: Validation Error Content-Type: application/json
Example Response:
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}Output Schema:
{
"properties": {
"detail": {
"items": {
"properties": {
"loc": {
"items": {},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| model | Yes | Generation model. `seedance-2.5` (highest quality, `480p` / `720p` / `1080p`, up to 30s), `seedance-2.0` (`480p` / `720p` / `1080p`, up to 15s), `seedance-2.0-fast` (faster and lower cost, `480p` / `720p` only, up to 15s), `seedance-2.0-mini` (lowest cost, `480p` / `720p` only, up to 15s). | |
| ratio | No | Output aspect ratio. Known values: `21:9`, `16:9`, `4:3`, `1:1`, `3:4`, `9:16`, `adaptive`. Optional — the provider picks a default when omitted. Does not affect billing. | |
| content | Yes | OpenAI-style content array describing the generation inputs. Must contain at least one `type=text` item (the prompt). May also include reference media, capped per kind and per model: up to 9 `image_url`, 3 `video_url`, and 3 `audio_url` items on the 2.0 models, or 30 / 10 / 10 on `seedance-2.5`. Including a `video_url` item makes this a video-to-video request and is priced accordingly. | |
| duration | Yes | Output video length in seconds: 4-15 on the 2.0 models, 4-30 on `seedance-2.5`. | |
| watermark | No | Whether to overlay the provider watermark on the output. Optional; the provider default applies when omitted. | |
| resolution | No | Output video resolution — one of `480p`, `720p`, `1080p`. Optional; defaults to `720p`. `1080p` is only supported by `seedance-2.0` and `seedance-2.5`. This is also the billing tier: cost is priced per (model, resolution, input-video) combination. | 720p |
| service_tier | No | Inference tier. `flex` selects cheaper offline/async inference. Optional; omit for standard online inference. | |
| generate_audio | No | Whether to generate an audio track for the video. Optional; the provider default applies when omitted. | |
| return_last_frame | No | Whether the provider should also return the generated video's last frame (surfaces as an extra field on `output`). Optional. |