> ## Documentation Index > Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt > Use this file to discover all available pages before exploring further. # Video Generation API > Complete API reference for OpenRouter's dedicated asynchronous Video Generation API. Submit jobs, poll status, stream video content, discover models, and configure webhooks. OpenRouter provides a dedicated asynchronous API for generating videos from text prompts, start and end frame images, and multimodal references. Because video generation takes significantly longer than text or image generation (typically 30 seconds to several minutes), requests follow an asynchronous submit-poll-download lifecycle. ## Endpoints The Video Generation API consists of four endpoints: | Method | Endpoint | Description | Response | | - | - | - | - | | `POST` | `/api/v1/videos` | Submits a video generation job | `202 Accepted` with job ID and polling URL | | `GET` | `/api/v1/videos/{jobId}` | Polls job status, progress, and download URLs | `200 OK` with status and video URLs | | `GET` | `/api/v1/videos/{jobId}/content` | Streams video binary bytes from the provider | `200 video/mp4` binary stream | | `GET` | `/api/v1/videos/models` | Lists video generation models and capabilities | `200 OK` with model parameter metadata | ## End-to-end workflow Video generation follows three sequential steps: 1. **Submit**: Send a generation request with a video model and prompt to `POST /api/v1/videos`. Receive a job ID (`id`) and relative polling URL (`polling_url`). 2. **Poll**: Query `GET /api/v1/videos/{jobId}` at regular intervals (recommended: every 10–30 seconds) until `status` becomes `completed` or `failed`. Alternatively, supply a `callback_url` to receive a webhook notification upon completion. 3. **Download**: Once completed, retrieve the generated video using either the signed storage URL (`urls[0]`) or the authenticated content proxy endpoint (`unsigned_urls[0]`). In a multi-user app, one API key can poll, download, and continue every job the app created. Record which end user owns each job ID, and check that ownership before you act on a job ID supplied by a client. ### cURL example ```bash theme={null} # Step 1: Submit a video generation job (Veo 3.1 supports durations: 4, 6, 8) SUBMIT_RESPONSE=$(curl -fsS -X POST "https://openrouter.ai/api/v1/videos" \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "model": "google/veo-3.1", "prompt": "A drone shot flying through a mist-shrouded redwood forest at sunrise, cinematic lighting, 4k", "duration": 6, "resolution": "720p", "aspect_ratio": "16:9" }') JOB_ID=$(echo "$SUBMIT_RESPONSE" | bun -e 'const j = await Bun.stdin.json(); console.log(j.id ?? "");') if [ -z "$JOB_ID" ] || [ "$JOB_ID" = "null" ]; then echo "Submission failed: $SUBMIT_RESPONSE" >&2 exit 1 fi echo "Submitted job: $JOB_ID" # Step 2: Poll until completion (capped at 40 iterations = 10 minutes) POLL_COUNT=0 while [ "$POLL_COUNT" -lt 40 ]; do sleep 15 POLL_COUNT=$((POLL_COUNT + 1)) STATUS_RESPONSE=$(curl -fsS "https://openrouter.ai/api/v1/videos/$JOB_ID" \ -H "Authorization: Bearer $OPENROUTER_API_KEY") || { echo "Polling request failed (HTTP error)" >&2 exit 1 } STATUS=$(echo "$STATUS_RESPONSE" | bun -e 'const j = await Bun.stdin.json(); console.log(j.status ?? "");') echo "Current status: $STATUS" if [ "$STATUS" = "completed" ]; then break elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ] || [ "$STATUS" = "expired" ]; then echo "Job terminated with status $STATUS" >&2 exit 1 fi done if [ "$STATUS" != "completed" ]; then echo "Timed out waiting for video generation" >&2 exit 1 fi # Step 3: Download video using the authenticated content endpoint curl -fsS "https://openrouter.ai/api/v1/videos/$JOB_ID/content" \ -H "Authorization: Bearer $OPENROUTER_API_KEY" \ -o output.mp4 echo "Saved video to output.mp4" ``` ### TypeScript example ```typescript theme={null} const apiKey = process.env.OPENROUTER_API_KEY; if (!apiKey) { throw new Error('OPENROUTER_API_KEY environment variable is required'); } const headers = { Authorization: `Bearer ${apiKey}`, 'Content-Type': 'application/json', }; type VideoJobStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired'; interface VideoJobResponse { id: string; generation_id?: string; status: VideoJobStatus; polling_url: string; urls?: string[]; expires_at?: number; unsigned_urls?: string[]; error?: string; usage?: { cost: number | null; is_byok?: boolean; }; } // Step 1: Submit job (Veo 3.1 supports durations: 4, 6, 8) const submitRes = await fetch('https://openrouter.ai/api/v1/videos', { method: 'POST', headers, body: JSON.stringify({ model: 'google/veo-3.1', prompt: 'A gentle ocean wave washing over golden sand in slow motion', duration: 6, resolution: '720p', aspect_ratio: '16:9', }), }); if (!submitRes.ok) { const errorText = await submitRes.text(); throw new Error(`Video submission failed (${submitRes.status}): ${errorText}`); } const job = (await submitRes.json()) as VideoJobResponse; console.log(`Job submitted: ${job.id}`); // Step 2: Poll status with a 10-minute deadline const deadline = Date.now() + 10 * 60_000; let completedJob: VideoJobResponse | null = null; while (!completedJob) { if (Date.now() > deadline) { throw new Error(`Timed out waiting for video job ${job.id} to complete`); } await new Promise((resolve) => setTimeout(resolve, 15000)); const pollRes = await fetch(`https://openrouter.ai/api/v1/videos/${job.id}`, { headers }); if (!pollRes.ok) { const errorText = await pollRes.text(); throw new Error(`Polling failed with HTTP ${pollRes.status}: ${errorText}`); } const statusData = (await pollRes.json()) as VideoJobResponse; console.log(`Status: ${statusData.status}`); if (statusData.status === 'completed') { completedJob = statusData; } else if (['failed', 'cancelled', 'expired'].includes(statusData.status)) { throw new Error(`Job ended with status ${statusData.status}: ${statusData.error ?? 'Unknown error'}`); } } // Step 3: Stream video bytes to file or downstream response const videoRes = await fetch(`https://openrouter.ai/api/v1/videos/${job.id}/content`, { headers: { Authorization: `Bearer ${apiKey}` }, }); if (!videoRes.ok) { throw new Error(`Video download failed (${videoRes.status})`); } const videoBytes = await videoRes.arrayBuffer(); console.log(`Downloaded video (${videoBytes.byteLength} bytes)`); ``` ### Python example ```python theme={null} import os import time import requests api_key = os.getenv("OPENROUTER_API_KEY") if not api_key: raise ValueError("OPENROUTER_API_KEY environment variable is required") headers = { "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", } # Step 1: Submit video job (Veo 3.1 supports durations: 4, 6, 8) submit_res = requests.post( "https://openrouter.ai/api/v1/videos", headers=headers, json={ "model": "google/veo-3.1", "prompt": "An architect sketching a modern house on parchment, pencil strokes forming 3D walls", "duration": 6, "resolution": "720p", "aspect_ratio": "16:9", }, ) submit_res.raise_for_status() job = submit_res.json() job_id = job["id"] print(f"Submitted video job: {job_id}") # Step 2: Poll until finished (capped at 40 iterations = 10 minutes) max_polls = 40 polls = 0 while polls < max_polls: time.sleep(15) polls += 1 poll_res = requests.get(f"https://openrouter.ai/api/v1/videos/{job_id}", headers=headers) poll_res.raise_for_status() poll_data = poll_res.json() status = poll_data["status"] print(f"Job status: {status}") if status == "completed": break if status in ("failed", "cancelled", "expired"): raise RuntimeError(f"Video job failed with status {status}: {poll_data.get('error')}") else: raise TimeoutError(f"Video job {job_id} did not finish within 10 minutes") # Step 3: Download video binary download_res = requests.get( f"https://openrouter.ai/api/v1/videos/{job_id}/content", headers={"Authorization": f"Bearer {api_key}"}, ) download_res.raise_for_status() with open("output.mp4", "wb") as f: f.write(download_res.content) print("Saved output.mp4") ``` ## Job lifecycle and statuses The `status` field on `GET /api/v1/videos/{jobId}` reflects the current state of generation: | Status | Type | Meaning | Next action | | - | - | - | - | | `pending` | In-flight | The request was admitted and queued for processing | Continue polling | | `in_progress` | In-flight | The provider is actively rendering the video frames | Continue polling | | `completed` | Terminal | Video rendering succeeded and output assets are ready | Retrieve output using `urls` or `unsigned_urls` | | `failed` | Terminal | The provider or validation failed; `error` explains the reason | Inspect `error` message and do not retry without parameter changes | | `cancelled` | Terminal | The job was cancelled before rendering completed | Terminal state | | `expired` | Terminal | The job exceeded maximum allowed time-to-live before settlement | Terminal state | ## Downloading outputs: `urls` vs `unsigned_urls` When a job reaches `status: "completed"`, the response payload provides two distinct ways to access the generated video: ```json theme={null} { "id": "gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt", "generation_id": "gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt", "status": "completed", "polling_url": "/api/v1/videos/gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt", "urls": [ "https://storage.openrouter.ai/generated-media/video-sample.mp4?token=..." ], "expires_at": 1789567274, "unsigned_urls": [ "/api/v1/videos/gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt/content?index=0" ], "usage": { "cost": 0.5, "is_byok": false } } ``` ### 1. Pre-signed storage URLs (`urls`) * **Authentication**: No `Authorization` header required. * **Validity**: Temporary, valid until the Unix timestamp in `expires_at`. * **Use case**: Safe for direct client browser playback (`