Video Generation

Video generation is asynchronous: the request submits a job, BullMQ polls the provider, and the rendered MP4 lands in the Library when ready.

Endpoints

POST /api/v1/ai/videos             submit job, returns job document
GET  /api/v1/ai/videos             list user's jobs
GET  /api/v1/ai/videos/:id         poll one job's status

Request body:

{
  prompt: string,
  provider?: "fal" | "runway",     // defaults to AI_VIDEO_PROVIDER (fal)
  duration?: number,               // seconds, 1–60, default 5
  aspect_ratio?: "16:9" | "9:16" | "1:1",
  model?: string,                  // override default per-provider model
}

Providers

Provider	Default model	Polling URL
fal	fal-ai/veo3/fast	https://queue.fal.run/<model>/requests/<id>/status
runway	gen3a_turbo	https://api.dev.runwayml.com/v1/tasks/<id>

Both poll every 5 seconds until completed or failed. Per-job timeout is 10 minutes — jobs that don't finish in that window are marked failed.

Queue

The ai-video queue:

• 1 retry attempt.
• removeOnComplete: 100, removeOnFail: 100.
• Job worker calls runAiVideoJob(), which polls the provider, downloads the result on success, and persists it to the file store.

Cost

20 credits per submission. Charged at submit time, not on completion — even failed jobs consume credits.

Job status values

pending → processing → completed (success) or pending → processing → failed (with error_message).

Related

Image Generation

Files Library

Credits