Webhook callbacks vs polling for long running video tasks
RelayDance supports two ways to receive results from long running video tasks submitted to POST /v1/video/generations: polling and webhook callbacks. With polling, you repeatedly call GET /v1/video/generations/{task_id} until the status is succeeded or failed, then read the video url from the result. With webhook callbacks, you set metadata.callback_url on the request and RelayDance POSTs the final state to your server when the task finishes. Both return the same final result; the difference is whether your client pulls status or RelayDance pushes it.
How polling works
Polling is a pull model. After you submit a task to POST /v1/video/generations with model, prompt, seconds, and metadata, you receive a task identifier. Your client then calls GET /v1/video/generations/{task_id} on an interval and inspects the status field. Continue polling while the task is in progress and stop when the status is succeeded or failed. On success, the result contains the video url. Polling requires no public endpoint on your side, which makes it straightforward for local development, scripts, and environments behind firewalls or NAT where inbound HTTP requests are not possible.
How webhook callbacks work
Webhook callbacks are a push model. Include metadata.callback_url when you submit the video task, and RelayDance POSTs the final state to that URL when the task reaches a terminal state. Your server receives the completed result, including the video url on success, without repeatedly querying for status. This approach suits production systems and high volume workloads because it removes the need for repeated status requests. It requires a publicly reachable endpoint that can accept the POST, so your server must be deployed where RelayDance can reach it over the network.
Comparison: polling vs webhook callbacks
| Aspect | Polling | Webhook callbacks |
|---|---|---|
| Direction | Client pulls status | RelayDance pushes result |
| Request used | GET /v1/video/generations/{task_id} | POST to your metadata.callback_url |
| Public endpoint required | No | Yes |
| Trigger | Repeated checks until succeeded or failed | Final state on completion |
| Result delivered | Video url in the response | Video url in the POSTed state |
| Best for | Local development, restricted networks | Production, higher volume |
Steps to choose and implement
- Create an API key at the RelayDance console and authenticate with
Authorization: Bearer YOUR_API_KEY. - Submit your task to
POST /v1/video/generationswith model, prompt, seconds, and metadata (ratio, resolution, generate_audio, content[] reference media). - For polling, omit
metadata.callback_urland callGET /v1/video/generations/{task_id}until status is succeeded or failed. - For webhooks, set
metadata.callback_urlto a publicly reachable endpoint and handle the POSTed final state. - Read the video url from the result on success. See the docs for details and live per-model rates.
Notes that apply to both methods
Both polling and webhook callbacks work across RelayDance models, including ByteDance Seedance 2.0, Seedance 1.5 Pro, HappyHorse video models, and Grok Imagine video models. Reference media go in metadata.content[] and are cited in the prompt as @image1 to @imageN, with up to 9 reference images, 3 reference videos, and 3 audio tracks per request, and clips up to 15 seconds. Failed or errored requests are never billed, regardless of how you retrieve the outcome. Payments are accepted via USDT and Stripe card. Mainstream model groups are priced 30 percent or more below official list prices.
FAQ
Do polling and webhooks return different results? No. Both deliver the same final result, including the video url on success. The difference is whether your client pulls status or RelayDance pushes the final state.
Do I need a public server for polling? No. Polling uses GET /v1/video/generations/{task_id} from your client, so no inbound endpoint is required. Webhook callbacks require a publicly reachable metadata.callback_url.
Am I billed if a video task fails? No. Failed or errored requests are never billed, whether you discover the failure through polling or a webhook callback.