Video

Asynchronous video generation, with optional narration and chained scenes.

Unlike other categories, video is asynchronous: the call immediately returns a job_id (HTTP 202), not the final result. Track its state via GET /v1/jobs/{job_id}.

Starting a generation

http

POST /v1/video/generate

json

{
  "prompt": "Un drone survole une plage au coucher du soleil.",
  "image_url": null,
  "duration_seconds": 5,
  "narration_text": null,
  "scenes": null,
  "model": null,
  "routing_strategy": "auto"
}

json

{ "job_id": "8b2a3be3-...", "status": "queued" }

Tracking the state

http

GET /v1/jobs/{job_id}

json

{
  "id": "8b2a3be3-...",
  "category": "video",
  "type": "text_to_video",
  "status": "completed",
  "provider": "vidu",
  "model": "viduq1",
  "result_url": "https://cdn.uploadscenter.com/file_...",
  "error": null,
  "created_at": "2026-08-31T17:14:04Z",
  "updated_at": "2026-08-31T17:24:41Z"
}

status is queued, processing, completed or failed. Poll at regular intervals (e.g. every 5 seconds) until one of the two final states. The official SDKs expose a .wait() shortcut that does this polling for you.

Narration (voiceover)

Provide narration_text to overlay a synthesized voiceover on the generated video. This is spoken text, distinct from the visual prompt, which only describes the scene for the video generator — no video provider generates audio natively, the narration is synthesized separately (ElevenLabs voice) and then merged in.

json

{
  "prompt": "Documentaire sous-marin, poissons tropicaux, recif corallien.",
  "narration_text": "Sous la surface, un monde silencieux et colore s'anime au rythme des courants.",
  "duration_seconds": 5
}

Scenes (video longer than one clip)

A clip generated by a single provider call typically lasts a few seconds, regardless of the requested duration. For a longer video (especially useful with a long narration), provide scenes — one visual description per segment of about duration_seconds, chained in order. Each scene is a separate provider call, billed separately.

json

{
  "prompt": "Presentation d'un chaton qui joue avec une balle.",
  "scenes": [
    "Un chaton tigre tapote une balle rouge dans un salon ensoleille, camera basse.",
    "Le chaton poursuit la balle sous le canape puis la ramene fierement, gros plan."
  ],
  "duration_seconds": 5,
  "narration_text": "Voici Moka, un chaton joueur qui pourchasse sa balle rouge avec entrain."
}

When scenes is provided, prompt is ignored for generation (the field remains required — use a short summary as its value).

Starting image

image_url turns a text-to-video generation into an image-to-video generation (the first clip animates the provided image).

Providers

Vidu, OpenAI (Sora).