Build Guides
Video Generation API: Request Design, Cost Planning, and Async Workflows
How to design a video-generation integration around longer-running jobs, per-generation pricing, retries, and user-facing progress.
What you will learn
- Represent generation as a durable job rather than a long blocking request.
- Use idempotency to avoid duplicate paid generations.
- Design progress, completion, and failure states for the user.
Before you start
- Basic HTTP and API knowledge
Leave with a concrete implementation checklist and a testable starting point.
Key takeaways
- Represent generation as a durable job rather than a long blocking request.
- Use idempotency to avoid duplicate paid generations.
- Design progress, completion, and failure states for the user.
Why video requests need a job model
Video generation can take longer than a typical chat request. Model the operation as a job with an accepted state, progress or polling strategy, completion result, and terminal error.
Do not keep an HTTP request open indefinitely just because the UI needs to show progress. Persist the job state and let the client reconnect.
Cost and idempotency
When billing is per generated item, retries can create duplicate spend. Give each user action an idempotency key and retry only when the provider or gateway documents the operation as safe to repeat.
Estimate cost from generation count, selected model, duration or output settings where applicable, and expected retry rate.
User experience
Return a clear accepted state, show what the user can do while processing, and provide a stable result URL. Surface failures with a next action instead of a generic timeout.
Keep media delivery separate from job orchestration so a completed result can be downloaded or reviewed independently.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Create a job record with an idempotency key.
- 2
Submit the generation request and store the provider reference.
- 3
Poll or receive completion without blocking the UI request.
- 4
Persist the result URL and terminal status.
Copy-ready example
const job = await db.jobs.create({ idempotencyKey, status: "queued" });
await queue.add("generate-video", { jobId: job.id, prompt });
return Response.json({ jobId: job.id, status: job.status }, { status: 202 });Frequently asked questions
Should I retry every failed video request?
No. First determine whether the failure happened before generation was accepted and whether the operation is safe to repeat.
Sources
- EasyAI documentationSource checked 2026-08-27