How to check video task status: states, polling intervals and when to download

To check a RelayDance video task status, send GET /v1/video/generations/{task_id} and read the returned status field. The task moves toward one of two terminal states: succeeded or failed. Poll this endpoint repeatedly until the state is terminal. When the status is succeeded, the response body contains the video url, which is the point at which you download the file. Alternatively, set metadata.callback_url to receive the final state by webhook.

What states a video task returns

A RelayDance video task resolves into one of two terminal states: succeeded or failed. After you submit a job with POST /v1/video/generations, the service returns a task_id that you use to query progress. You poll GET /v1/video/generations/{task_id} until the status reads succeeded or failed. On success, the result object includes the video url. On failure, no media url is produced, and the billing consequence is defined by RelayDance: 据 relaydance.com 官方文档, 「Failed or errored requests are never billed」. This means polling a job that ends in the failed state carries no cost for the generation itself. See live per-model rates at https://relaydance.com/models.

How to poll the task endpoint

Polling means calling GET /v1/video/generations/{task_id} in a loop until the state is terminal. Because RelayDance is OpenAI-compatible, you keep your existing SDK and only change the base URL: 据 relaydance.com/docs 官方文档, 「Set base_url to https://relaydance.com/v1 and keep your OpenAI SDK」. Each request must carry the header Authorization: Bearer YOUR_API_KEY, with keys created at the console. Stop polling as soon as the status returns succeeded or failed. Clips can run up to 15 seconds, and a single request accepts up to 9 reference images, 3 reference videos and 3 audio tracks, so longer or reference-heavy jobs may take more poll cycles before reaching a terminal state. Read the API protocol at https://relaydance.com/docs.

When to download the result

Download only after the task status reaches succeeded, because that is when the response contains the video url. Follow these numbered steps:

1. Submit the job with POST /v1/video/generations and store the returned task_id.
2. Call GET /v1/video/generations/{task_id} on an interval.
3. If the status is succeeded, read the video url from the result and download the file.
4. If the status is failed, stop; no media url is returned and the request is not billed.

For a hands-off flow, set metadata.callback_url so the final state is POSTed to your server, removing the need to poll at all. Reference media placed in metadata.content[] are cited in the prompt as @image1 to @imageN.

Cost context for status checks

Billing is pay-as-you-go per generated video, so only succeeded jobs incur a generation charge. Concrete per-model rates help you plan: Seedance 2.0 720p is about $0.190 per second, Seedance 2.0 1080p is about $0.470 per second, Seedance Fast is about $0.152 per second, and Seedance native 4K is about $4.90 per 5-second clip. For images, output is free and only input is billed, with image-to-image from about CNY 0.035. The following table summarizes the video rates.

FAQ

What are the terminal task states? A video task ends in either succeeded or failed. When the state is succeeded, the result contains the video url to download.

Can I avoid polling? Yes. Set metadata.callback_url and the final state is POSTed to your server as a webhook.

Am I charged if a task fails? No. 据 relaydance.com 官方文档, 「Failed or errored requests are never billed」, and billing is pay-as-you-go per generated video.