Query a task
GET /api/v3/contents/generations/tasks/{task_id}
Request parameters
| Location | Parameter | Type | Required | Description |
|---|---|---|---|---|
| Path | task_id | string | Yes | Task ID from the creation response. Currently task_id and id in the creation response have the same value. |
| Header | Authorization | string | Yes | Bearer YOUR_API_KEY. |
| Header | Content-Type | string | No | Recommended: application/json; GET requests do not have a request body. |
curl -X GET /api/v3/contents/generations/tasks/task_xxx \
-H "Authorization: Bearer YOUR_API_KEY"Successful response
{
"id": "260e3207-aefd-4ca8-8f35-537a5990d172",
"model": "doubao-seedance-2-0-260128",
"status": "succeeded",
"created_at": 1790754352,
"updated_at": 1790754482,
"content": {
"video_url": "https://media.example.com/seedance/260e3207-aefd-4ca8-8f35-537a5990d172/3/video_url-84990293807539211ad19f60.mp4?X-Tos-Algorithm=TOS4-HMAC-SHA256&X-Tos-Credential=AKLTYmNjZDFkMmQ5ZWU0NDZjODlkOWJjMzZmMThiNjE1OWU%2F20260930%2Fcn-beijing%2Ftos%2Frequest&X-Tos-Date=20260930T074817Z&X-Tos-Expires=86400&X-Tos-SignedHeaders=host&X-Tos-Signature=338b044e8c6e60e0fa3f68655c78bd7bc228569deb8cc50bc02105b9d472f048"
},
"usage": {
"completion_tokens": 40594,
"total_tokens": 40594
},
"seed": 68888,
"resolution": "480p",
"ratio": "16:9",
"duration": 4,
"framespersecond": 24,
"generate_audio": true,
"draft": false,
"service_tier": "default",
"execution_expires_after": 172800
}Task statuses are typically queued, running, succeeded, or failed. After success, download content.video_url promptly.
Successful response fields
| Field | Type | Description |
|---|---|---|
id | string | Platform task UUID. |
model | string | Model name and version used for the task; exact format follows the API response. |
status | string | queued, running, succeeded, or failed. |
created_at / updated_at | integer | Creation and update time as Unix timestamps. |
content | object | Generation result container. |
content.video_url | string | Video URL on success; download within the validity period. |
content.last_frame_url | string | Last frame image URL; returned when return_last_frame: true is set at creation. |
duration | number | Actual output video duration (seconds). |
ratio | string | Actual output aspect ratio. |
resolution | string | Actual output resolution. |
output_format | string | Actual output format, e.g. mp4 or mov. |
framespersecond | integer | Output video frame rate. |
generate_audio | boolean | Whether audio was generated. |
seed | integer | Random seed used for this generation. |
usage | object | Task usage information. |
usage.completion_tokens / usage.total_tokens | integer | Generation token usage. |
usage.tool_usage.web_search | integer | Number of web search calls; returned only when web search is enabled. |
execution_expires_after | integer | Task execution validity configuration. |
service_tier | string | Service tier. |
priority | integer | Task priority. |
draft | boolean | Whether the 2.5 task is a draft; true for draft, false for formal video. |
draft_task_id | string | Platform draft task UUID when reusing a draft on 2.5. |
tools | array | Tools actually used for this task; not returned when none used. |
safety_identifier | string | End-user identifier; returned as-is if set at creation. |
Failed response
{
"id": "260e3207-aefd-4ca8-8f35-537a5990d172",
"model": "doubao-seedance-2-5-260628",
"status": "failed",
"error": {
"code": "OutputVideoSensitiveContentDetected",
"message": "The request failed because the output video may contain sensitive information. Request ID: task_xxx"
},
"created_at": 1718049470,
"updated_at": 1718049470
}Failed response fields
| Field | Type | Description |
|---|---|---|
id | string | Failed task ID. |
model | string | Model name and version used for the task; exact format follows the API response. |
status | string | failed on failure. |
error | object | Error object. |
error.code | string | Error code, e.g. OutputVideoSensitiveContentDetected. |
error.message | string | Error description. |
created_at / updated_at | integer | Creation and update time as Unix timestamps. |
Successful response example
The following is a redacted structural example; task ID, model version, timestamps, and artifact URLs are placeholders.
{
"id": "00000000-0000-4000-8000-000000000001",
"model": "ACTUAL_MODEL_VERSION",
"status": "succeeded",
"created_at": 1700000000,
"updated_at": 1700000060,
"content": {
"video_url": "https://example.com/generated-video.mp4"
},
"usage": {
"completion_tokens": 100,
"total_tokens": 100
}
}Seedance 2.5 success example
2.5 uses the same query endpoint. The following is an example response after a formal video succeeds:
{
"id": "550e8400-e29b-41d4-a716-446655440025",
"model": "seedance-2.5",
"status": "succeeded",
"created_at": 1792800000,
"updated_at": 1792800060,
"content": {
"video_url": "https://media.example.com/generated/seedance25.mp4"
},
"resolution": "720p",
"ratio": "16:9",
"duration": 20,
"generate_audio": true,
"draft": false
}2.5 parameter or task type incompatibilities may return errors only after acceptance; poll until a clear terminal state. Do not judge generation success based solely on the ID returned at creation.
Task statuses
| Status | Meaning | Continue polling? |
|---|---|---|
queued | Queued | Yes |
running | Running | Yes |
succeeded | Succeeded | No; retrieve the output |
failed | Failed | No; handle the error |
cancelled | Cancelled | No |
expired | Timed out | No |
Polling recommendations
Set an interval, a maximum attempt count, and an overall timeout for queries. Do not poll indefinitely after failure or timeout, and do not automatically submit a new generation task just because the wait timed out.
Artifact links and downloads
- Platform default storage: Videos and last frames use access links valid for 24 hours from issuance. Download or save to your own storage promptly once results are ready.
- Repeated queries: Returned artifact links are not automatically extended by repeated queries. A task record being queryable does not mean the artifact link is still accessible.
- Custom storage: After successful transfer, the address and access permissions are determined by your storage repository configuration; keep the repository and files available.
This endpoint returns platform storage or custom storage addresses; do not apply Volcano Engine's source artifact URL download limits directly to these addresses. Save the full artifact URL including its query parameters; when downloading, do not construct, truncate signature parameters, or send the API key on your own.
Custom storage status
After specifying custom storage via the creation request's oss-id, the query result reflects both model generation and artifact transfer progress.
custom_storage_status:PENDINGpending transfer,PROCESSINGtransferring,SUCCESStransfer succeeded,FAILEDtransfer failed.can_retry_transfer:boolean.truemeans there are failed artifacts with still-accessible sources that can be retried. This field only indicates retry conditions; it does not automatically initiate a retry.transfer_source_expired:boolean.truemeans at least one failed artifact's source has expired or is no longer downloadable.transfer_error_message: Transfer failure description.
can_retry_transfer and transfer_source_expired may both be true, meaning among multiple failed artifacts, some are still retryable and some sources have expired. When there are no failed artifacts, transfer_source_expired may be omitted.
For example, when the model has generated successfully and the artifact is still being transferred, the response may look like:
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"model": "seedance-2.0",
"status": "succeeded",
"created_at": 1792800000,
"updated_at": 1792800060,
"custom_storage_status": "PROCESSING",
"can_retry_transfer": false
}At this point there is no usable artifact URL yet; continue polling for transfer progress. If transfer fails, check your storage repository configuration and address the transfer issue; do not automatically create a new video generation task just because the transfer failed.
Query failures and polling recommendations
- HTTP 400: Task UUID or query parameters do not meet requirements.
- HTTP 401: Key is invalid, disabled, or expired.
- HTTP 403: Authentication conditions such as account or IP whitelist are not satisfied.
- HTTP 404: The task does not exist or is not accessible to the current API key.
- HTTP 429: Public rate limit triggered; reduce query frequency and retry.
- HTTP 500, 503: Service exception or task result temporarily unavailable; retain the task ID and retry later.
Common query error codes are InvalidParameter (parameters do not meet requirements), TaskNotFound (task not accessible), and TaskResultUnavailable (result temporarily unavailable). For authentication errors and handling, see Authentication.
For request failure error body format, see Error handling. Task status=failed means a failed task was queried, and HTTP may still be 200; this is different from the query request itself failing.
It is recommended to start with a query every 3–5 seconds and gradually increase the interval when rate-limited or temporarily unavailable. After client-side wait timeout, retain the task ID and X-Request-ID, resume queries later or contact support for troubleshooting; do not treat wait timeout as task rejection or automatically issue a refund. Stop polling after receiving a successful response and obtaining the artifact; also stop regular polling after receiving failed, cancelled, or expired. When a query request fails, handle it by HTTP error first; do not write the HTTP error code directly into the task's status.
Protocol reference
Task IDs, visibility scope, response fields, and artifact address rules on this platform follow this document.

