Skip to content
Reading settings
Seedance native protocol
GET/api/v3/contents/generations/tasks/{task_id}

Query a task ​

GET /api/v3/contents/generations/tasks/{task_id}

Request parameters ​

LocationParameterTypeRequiredDescription
Pathtask_idstringYesTask ID from the creation response. Currently task_id and id in the creation response have the same value.
HeaderAuthorizationstringYesBearer YOUR_API_KEY.
HeaderContent-TypestringNoRecommended: application/json; GET requests do not have a request body.
bash
curl -X GET /api/v3/contents/generations/tasks/task_xxx \
  -H "Authorization: Bearer YOUR_API_KEY"

Successful response ​

json
{
	"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 ​

FieldTypeDescription
idstringPlatform task UUID.
modelstringModel name and version used for the task; exact format follows the API response.
statusstringqueued, running, succeeded, or failed.
created_at / updated_atintegerCreation and update time as Unix timestamps.
contentobjectGeneration result container.
content.video_urlstringVideo URL on success; download within the validity period.
content.last_frame_urlstringLast frame image URL; returned when return_last_frame: true is set at creation.
durationnumberActual output video duration (seconds).
ratiostringActual output aspect ratio.
resolutionstringActual output resolution.
output_formatstringActual output format, e.g. mp4 or mov.
framespersecondintegerOutput video frame rate.
generate_audiobooleanWhether audio was generated.
seedintegerRandom seed used for this generation.
usageobjectTask usage information.
usage.completion_tokens / usage.total_tokensintegerGeneration token usage.
usage.tool_usage.web_searchintegerNumber of web search calls; returned only when web search is enabled.
execution_expires_afterintegerTask execution validity configuration.
service_tierstringService tier.
priorityintegerTask priority.
draftbooleanWhether the 2.5 task is a draft; true for draft, false for formal video.
draft_task_idstringPlatform draft task UUID when reusing a draft on 2.5.
toolsarrayTools actually used for this task; not returned when none used.
safety_identifierstringEnd-user identifier; returned as-is if set at creation.

Failed response ​

json
{
  "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 ​

FieldTypeDescription
idstringFailed task ID.
modelstringModel name and version used for the task; exact format follows the API response.
statusstringfailed on failure.
errorobjectError object.
error.codestringError code, e.g. OutputVideoSensitiveContentDetected.
error.messagestringError description.
created_at / updated_atintegerCreation 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.

json
{
  "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:

json
{
  "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 ​

StatusMeaningContinue polling?
queuedQueuedYes
runningRunningYes
succeededSucceededNo; retrieve the output
failedFailedNo; handle the error
cancelledCancelledNo
expiredTimed outNo

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.

  • 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: PENDING pending transfer, PROCESSING transferring, SUCCESS transfer succeeded, FAILED transfer failed.
  • can_retry_transfer: boolean. true means 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. true means 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:

json
{
  "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.