Batch video generation in Python: concurrency, rate limits and retry queues

Batch video generation with RelayDance uses an OpenAI-compatible API: submit tasks with POST /v1/video/generations, then poll GET /v1/video/generations/{task_id} until status is succeeded or failed, or use webhook mode via metadata.callback_url. For concurrency, run parallel submissions and manage retries with a queue that re-submits only truly failed tasks. Because failed or errored requests are never billed, retry logic carries no billing risk. See relaydance.com/docs.

How to set up the client and submit batch tasks

Point your existing OpenAI SDK at the RelayDance base URL and submit tasks in a loop. According to the official relaydance.com/docs, 「Set base_url to https://relaydance.com/v1 and keep your OpenAI SDK」. Authenticate with an Authorization: Bearer YOUR_API_KEY header, using keys created at the console. Each POST /v1/video/generations request accepts model, prompt, seconds, and metadata (ratio, resolution, generate_audio, callback_url, and content[] reference media). Reference media are cited in the prompt as @image1 to @imageN, with up to 9 reference images, 3 reference videos, and 3 audio tracks per request. Clips can run up to 15 seconds, so plan batch job sizing around those per-request limits.

Managing concurrency and polling

Run concurrent submissions with a worker pool, then poll each task_id independently until it resolves. After POST /v1/video/generations returns a task_id, call GET /v1/video/generations/{task_id} on an interval until status is succeeded or failed; the succeeded result contains the video url. For larger batches, prefer webhook mode: set metadata.callback_url and the final state is POSTed to your server, which removes polling overhead. A practical pattern is a bounded queue of pending task_ids: a fixed number of Python worker threads submit tasks, a poller advances each task, and completed downloads free a slot for the next submission.

Building a retry queue safely

Design retries around the fact that failed or errored requests are never billed. According to the official relaydance.com docs, 「Failed or errored requests are never billed」, so re-submitting a task that returned status failed does not add cost. Implement a retry queue with a maximum attempt count and exponential backoff (for example, retry after a short delay, then a longer one). Keep a per-task attempt counter, move exhausted tasks to a dead-letter list for inspection, and log the returning error before re-queuing. Because billing is pay-as-you-go per generated video, you are charged only for clips that reach succeeded status, which keeps retry-heavy batches predictable.

Estimating batch cost

Cost per clip depends on the model and resolution, and only succeeded videos are billed. Live per-model rates are at relaydance.com/models. The table below lists reference figures for planning batch budgets.

To estimate a run, multiply the per-second rate by seconds per clip, then by the number of clips that reach succeeded status. Payments are supported via USDT and Stripe card.

Numbered steps for a batch pipeline

1. Set base_url to https://relaydance.com/v1 and add the Authorization: Bearer YOUR_API_KEY header.
2. Submit each job with POST /v1/video/generations, including model, prompt, seconds, and metadata.
3. Attach up to 9 reference images, 3 reference videos, and 3 audio tracks in metadata.content[], cited as @image1 to @imageN.
4. Poll GET /v1/video/generations/{task_id}, or set metadata.callback_url for webhook delivery.
5. On status failed, push the task to a retry queue with a max attempt limit and backoff.
6. On status succeeded, download the returned video url and free the worker slot.

FAQ

Do retries cost money? No. Failed or errored requests are never billed, so re-submitting a task that returned status failed adds no charge; only succeeded videos are billed pay-as-you-go.

Can I keep my existing OpenAI SDK? Yes. Set base_url to https://relaydance.com/v1 and keep your OpenAI SDK, then authenticate with a Bearer API key from the console.

How many reference assets can one request hold? Up to 9 reference images, 3 reference videos, and 3 audio tracks per request, with clips up to 15 seconds.