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. The task cost is charged in
USD from the account wallet on the first successful poll, not at submit
time. At submit time the wallet balance is checked against an
upper-bound cost estimate; an insufficient balance returns 402 with
`X-Usd-Required-*` headers and no task is created.
Request body:
- `model` (string, required): `seedance-2.0` or `seedance-2.0-fast`.
- `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 likewise
`video_url` / `audio_url`), capped at 9 image, 3 video, and 3 audio
items. `role` is one of `first_frame`, `last_frame`,
`reference_image`, `reference_video`, `reference_audio`. Reference
URLs must be publicly reachable.
- `resolution` (string, optional, default `720p`): `480p`, `720p`,
or `1080p`. `1080p` is not supported by `seedance-2.0-fast`. Also
the billing tier.
- `duration` (integer, required): output length in seconds, 4-15.
- `ratio` (string, optional): output aspect ratio — `21:9`, `16:9`,
`4:3`, `1:1`, `3:4`, `9:16`, or `adaptive`.
- `generate_audio` (boolean, optional): generate an audio track.
- `watermark` (boolean, optional): overlay the provider watermark.
- `service_tier` (string, optional): `flex` for cheaper offline
inference.
- `return_last_frame` (boolean, optional): also return the video's
last frame on `output`.
Any further unrecognized top-level fields are forwarded to the
generation provider unchanged.
Response `data`:
- `taskId` (string): identifier to poll, format `task_video_<id>`.
- `status` (string): always `pending` immediately after submit.
### Responses:
**200**: Successful Response (Success Response)
Content-Type: application/json
**Example Response:**
```json
{
"success": true,
"meta": {
"requestId": "Requestid",
"timestamp": "Timestamp"
}
}
```
**Output Schema:**
```json
{
"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:**
```json
{
"detail": [
{
"loc": [],
"msg": "Message",
"type": "Error Type",
"ctx": {}
}
]
}
```
**Output Schema:**
```json
{
"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"
}
```