Add AI video generation to a Next.js app: API routes, polling and a progress UI

To add AI video generation to a Next.js app, use RelayDance's OpenAI-compatible API: create a server-side API route that submits a POST to /v1/video/generations, then poll GET /v1/video/generations/{task_id} from another route until the status is succeeded or failed, and update a client progress UI on each poll. Set the base URL to https://relaydance.com/v1 and authenticate with a Bearer API key.

Configure the API client in a Next.js route handler

Configure your video calls inside a server-side Next.js route handler so the API key stays private. According to the official relaydance.com/docs, 「Set base_url to https://relaydance.com/v1 and keep your OpenAI SDK」, which means you reuse the OpenAI SDK and only change the base URL. Set the header Authorization: Bearer YOUR_API_KEY using a key created at the console. Place this logic in a route like app/api/video/route.ts so the browser never sees the secret. The connection is OpenAI-compatible, so no BytePlus enterprise account or KYC is required. Reference media (up to 9 images, 3 videos, and 3 audio tracks) go in metadata.content[] and are cited in the prompt as @image1 to @imageN.

Submit a task and poll for the result

Submit a task with a POST to /v1/video/generations, then poll a second route until the job finishes. The submit body includes model, prompt, seconds, and metadata (ratio, resolution, generate_audio, callback_url). Clips can run up to 15 seconds.

1. POST prompt and parameters to /v1/video/generations; capture the returned task_id.
2. Poll GET /v1/video/generations/{task_id} on an interval.
3. When status is succeeded, read the video url from the result.
4. When status is failed, surface the error in the UI.

As an alternative to polling, set metadata.callback_url and the final state is POSTed to your server via webhook.

Build the progress UI on the client

Build the progress UI by having the client call your polling route and render each status update. A React component can call fetch('/api/video/status?task_id=...') every few seconds, storing the returned status in state. Show a spinner while the status is pending, then swap in a <video> element with the result url once the status is succeeded. Because RelayDance is pay-as-you-go per generated video, errored attempts carry no charge. According to the official relaydance.com docs, 「Failed or errored requests are never billed」, so retry logic in your UI does not incur extra cost for failed polls or rejected submissions.

Estimate cost per generation

Estimate cost from the per-second and per-clip rates published at relaydance.com/models. Billing is pay-as-you-go and rates vary by model and resolution.

For gpt-image-2, image output is free (only input is billed), and 4K and 1K output cost the same. Payments are accepted via USDT and Stripe card.

FAQ

Do I pay for failed video generations? No. Failed or errored requests are never billed, so retries in your Next.js UI add no cost for rejected jobs.

Can I use the OpenAI SDK directly? Yes. The API is OpenAI-compatible; set the base URL to https://relaydance.com/v1 and keep your existing OpenAI SDK.

How long can a generated clip be? Clips can run up to 15 seconds per request, with up to 9 reference images, 3 reference videos, and 3 audio tracks supplied in metadata.content[].