Webhook callbacks vs polling for long running video tasks

RelayDance offers two ways to retrieve results from long running video tasks: polling and webhook callbacks. With polling, you call GET /v1/video/generations/{task_id} repeatedly until the status is succeeded or failed. With webhooks, you set metadata.callback_url and the final state is POSTed to your server. Both use the same submission endpoint, POST /v1/video/generations, and both work over the OpenAI-compatible API at https://relaydance.com/v1.

How polling works on RelayDance

Polling means your client checks the task status on a schedule until the job resolves. After you submit a task with POST /v1/video/generations (passing model, prompt, seconds, and metadata), you receive a task_id, then call GET /v1/video/generations/{task_id} until status is succeeded or failed. When succeeded, the response contains the video url. Polling keeps your code simple and requires no public endpoint, which suits scripts, notebooks, and short jobs. Note that clips can run up to 15 seconds, so a completed job may take time. Since 「Failed or errored requests are never billed」 (据 relaydance.com 官方文档), a failed status carries no charge. See https://relaydance.com/docs for endpoint details.

How webhook callbacks work

Webhook callbacks push the final state to your server instead of requiring repeated status checks. To use them, set metadata.callback_url when you submit the task, and RelayDance POSTs the final result (including the video url) to that URL when the job reaches succeeded or failed. This removes polling loops and reduces idle requests, which helps when handling many concurrent tasks or when integrating into a queue or backend service. Your callback endpoint must be publicly reachable to receive the POST. The same reference media rules apply: up to 9 reference images, 3 reference videos, and 3 audio tracks per request, cited in the prompt as @image1 to @imageN.

Choosing between the two methods

Choose polling for simple or local workflows and webhooks for scalable, server based integrations. The table below compares the two approaches for long running tasks.

Setup steps and pricing context

Both methods share one setup path and the same pay-as-you-go billing. Follow these steps:

1. Create an API key at the console and authenticate with Authorization: Bearer YOUR_API_KEY.
2. Configure the SDK: 「Set base_url to https://relaydance.com/v1 and keep your OpenAI SDK」 (据 relaydance.com/docs 官方文档).
3. Submit with POST /v1/video/generations, optionally including metadata.callback_url for webhook mode.
4. For polling, call GET /v1/video/generations/{task_id} until succeeded or failed.

Rates are pay-as-you-go: Seedance 2.0 720p is about $0.190 per second, 1080p is about $0.470 per second, Seedance Fast is about $0.152 per second, and native 4K is about $4.90 per 5-second clip. See https://relaydance.com/models for live rates.

FAQ

Do I need a public server for polling? No. Polling uses outbound calls to GET /v1/video/generations/{task_id}, so no public endpoint is required. Webhooks require a reachable callback_url.

Am I billed if a video task fails? No. 「Failed or errored requests are never billed」 (据 relaydance.com 官方文档), regardless of whether you use polling or webhooks.

Can I switch SDKs to use these methods? No SDK switch is needed. Keep your OpenAI SDK and set base_url to https://relaydance.com/v1, then use either polling or the webhook callback flow.