Skip to main content
GET
Note for users in mainland China: Please use https://toapis.cn as the API endpoint (Base URL). Replace https://toapis.com with https://toapis.cn in the examples in this document.
  • Query async video generation task execution status and results
  • Real-time status updates and progress tracking
  • Get generated videos when task completes
  • Multi-language support (zh/en/ko/ja)
All video generation tasks are executed asynchronously. After submitting a task, you need to query the status and results via the query endpoint.
Seedance video tasks that require asset review use this same status endpoint. queued may include asset preparation and review; receiving a task does not mean video generation has started. Preparation defaults to 20 minutes per round, excluding subsequent video generation. Inspect error.message on failure.
Ordinary image and video tasks can also be queried with GET /v1/tasks/{task_id}, using the same usage and billing definitions. This page describes responses from the generation-task query path shown above. Examples illustrate the fields, not current model prices or a fixed billing mode. Use the fields and amounts returned for the actual task.

Seedance original and fallback URLs

For Seedance tasks with original URL delivery enabled, result.data[].url preserves the original upstream video URL. Use url first and switch to fallback_url on the same result item only if the primary URL cannot be accessed. The platform does not switch URLs automatically based on the client region. Fallback fields are optional and are returned only when a copy is available. They may be omitted when original URL delivery is disabled, a copy is unavailable, or a historical task has no copy. Omission does not mean generation failed. For the last frame, use last_frame_url first and fallback_last_frame_url only if it cannot be accessed. A fallback does not extend the original URL validity period. Download promptly if you need long-term storage.

Authorizations

string
required
All endpoints require Bearer Token authenticationGet your API Key:Visit the API Key Management Page to get your API KeyAdd it to the request header:

Path Parameters

string
required
Task ID returned by the video generation API

Response

string
Unique task identifier
string
Optional customer business ID, returned only when client_business_id was supplied at task creation.
string
Object type, always generation.task
string
Task status
  • queued - Queued for processing
  • in_progress - Processing
  • completed - Successfully completed
  • failed - Failed
integer
Task progress percentage (0-100)
string
Video generation model used
integer
Optional platform task update time as a Unix timestamp, currently returned for Seedance Global. generation.updated_at is the upstream update time.
integer
Task creation time (Unix timestamp)
integer
Task finish time as a Unix timestamp. This query path returns it for successful or failed tasks when a finish time has been saved.
integer
Task completion time (Unix timestamp, only returned when completed)
integer
Video URL expiration time (Unix timestamp, only returned on completion)
object
Task result (only returned on success)
object
Optional Seedance generation metadata. Only saved, publicly available fields are returned; defaults are not filled in. These parameters describe generation and do not replace the billing quantities in top-level usage.generation.usage is an existing compatibility field that may contain completion_tokens and total_tokens. It may be absent or differ from final billed quantities. Do not add it to top-level usage; use top-level usage for billing quantities.
object
Optional billing quantities, video-token details, and tool counts. See Task usage fields for units and omission rules.charge_type through input_images are billing quantities and are returned only together with billing.status=settled. Fixed-price videos return the quantities confirmed at submission; videos settled by actual duration or tokens return the final settled quantities. Fields that are not returned are omitted, not filled with zeros.
object
Optional platform billing status and confirmed charge. Billing status is independent of generation status; completed does not guarantee settlement. A missing object does not mean the task was free. See Pricing and Actual Charges.Task Webhook data.billing uses the same confirmation rules and values.
object
Error information (only returned on failure)Error codes and messages are normally strings. Seedance Global preserves the original upstream JSON values in error.code and error.message, including numbers or null. Missing upstream fields are not replaced with platform defaults.

Task Status Reference

Polling Strategy

Python Polling Example

Resource Expiration

Generated video URLs are valid for 24 hours
  • Please download and save videos within the validity period
  • expires_at field indicates video expiration time (Unix timestamp)
  • Expired videos cannot be accessed; to regenerate, submit a new task
  • Thumbnails expire simultaneously with videos

Errors and failure reasons

See the error reference for request errors, task failures, specific causes, and recovery guidance. A successful query still requires checking task status; HTTP status is not a business error code.

Performance Tips

Video generation takes longer, recommendations:
  1. Use the ToAPIs Task Webhook: Prefer Webhooks and keep polling as fallback
  2. Set a Reasonable Polling Interval: At least 5–10 seconds with jitter; on 429, honor Retry-After and back off exponentially
  3. Set Timeout: Long videos may take 5-10 minutes, set reasonable timeout
  4. Download Promptly: Videos expire after 24 hours, save to your storage immediately
See Async task rate limits. A batch query accepts at most 100 task IDs.