Webhook callbacks vs polling for long running video tasks

RelayDance supports two methods for retrieving long running video task results: 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 bill only completed generations on a pay-as-you-go basis.

How polling works

Polling means your client repeatedly queries the task endpoint until the job finishes. After submitting a task with POST /v1/video/generations, you receive a task_id, then call GET /v1/video/generations/{task_id} until status returns succeeded or failed; the result contains the video url. This method requires no public server, which suits local scripts and testing. Because clips can run up to 15 seconds and reference media may include up to 9 images, 3 videos and 3 audio tracks, generation can take time, so polling adds repeated requests during the wait. The interface stays OpenAI compatible throughout. See the live rates at relaydance.com/models.

How webhook callbacks work

Webhook callbacks push the final task state to your server instead of requiring repeated queries. To use this mode, set metadata.callback_url when you submit POST /v1/video/generations; when the task reaches succeeded or failed, RelayDance POSTs the final state, including the video url, to that URL. This removes the need for a polling loop and suits backend services that can receive inbound HTTP requests. Both methods rely on the same OpenAI-compatible setup. According to the official relaydance.com/docs: "set base_url to https://relaydance.com/v1 and keep your OpenAI SDK", so existing OpenAI SDK code works with either retrieval method. Full details are in the documentation.

Comparison: polling vs webhooks

The two methods differ in infrastructure needs and request volume, but share billing rules and endpoints.

Billing and failed tasks

Both methods bill only successful generations, so failed retrievals carry no cost. RelayDance uses pay-as-you-go pricing per generated video; for example, Seedance 2.0 is about $0.190 per second at 720p and about $0.470 per second at 1080p, while Seedance Fast is about $0.152 per second and Seedance native 4K is about $4.90 per 5 second clip (see relaydance.com/models). According to the official relaydance.com docs: "failed or errored requests are never billed". This rule applies whether you detect the failed status via polling or receive it through a webhook POST, so error handling does not add charges in either mode.

Steps to submit and retrieve a task

The following sequence applies to both retrieval methods, with one optional field deciding the mode.

1. Set base_url to https://relaydance.com/v1 and keep the OpenAI SDK.
2. Add the header Authorization: Bearer YOUR_API_KEY (create keys at the console).
3. Submit with POST /v1/video/generations using model, prompt, and seconds, plus metadata (ratio, resolution, generate_audio).
4. For webhooks, add metadata.callback_url; otherwise prepare to poll.
5. Reference media go in metadata.content[] and are cited in the prompt as @image1 to @imageN (up to 9 images, 3 videos, 3 audio tracks).
6. Polling: call GET /v1/video/generations/{task_id} until succeeded or failed. Webhook: read the POSTed final state on your server.

FAQ

Do I need a public server for webhooks? Yes. Webhook callbacks POST the final state to your metadata.callback_url, so your server must accept inbound HTTP requests. Polling does not require a public endpoint.

Are failed tasks billed in either mode? No. According to the official relaydance.com docs: "failed or errored requests are never billed", which applies to both polling and webhook retrieval.

Can I keep using the OpenAI SDK? Yes. Change base_url to https://relaydance.com/v1 and keep the OpenAI SDK to call the API with either retrieval method.