Video Generation

OpenRouter supports video generation from text prompts (and optional reference images) via a dedicated asynchronous API. You can find the supported models, their capabilities, and pricing by filtering our model list by video output.

Model Discovery

You can find video generation models in several ways:

Via the Video Models API

Use the dedicated video models endpoint to list all available video generation models along with their supported parameters:

$
curl "https://openrouter.ai/api/v1/videos/models"

The response returns a data array where each model includes:

1
{
2
  "data": [
3
    {
4
      "id": "google/veo-3.1",
5
      "canonical_slug": "google/veo-3.1",
6
      "name": "Google: Veo 3.1",
7
      "description": "...",
8
      "created": 1719792000,
9
      "supported_resolutions": ["720p", "1080p"],
10
      "supported_aspect_ratios": ["16:9", "9:16", "1:1"],
11
      "supported_sizes": ["1280x720", "1920x1080"],
12
      "pricing_skus": {
13
        "per-video-second": "0.50",
14
        "per-video-second-1080p": "0.75"
15
      },
16
      "allowed_passthrough_parameters": ["output_config"]
17
    }
18
  ]
19
}

Use this endpoint to check which resolutions, aspect ratios, and passthrough parameters are supported by each model before submitting a generation request.

Via the Models API

You can also use the output_modalities query parameter on the Models API to discover video generation models:

$
# List only video generation models
$
curl "https://openrouter.ai/api/v1/models?output_modalities=video"

On the Models Page

Visit the Models page and filter by output modalities to find models capable of video generation. Look for models that list "video" in their output modalities.

How It Works

Unlike text or image generation, video generation is asynchronous because generating video takes significantly longer. The workflow is:

1. Submit a generation request to POST /api/v1/videos
2. Receive a job ID and polling URL immediately
3. Poll the polling URL (GET /api/v1/videos/{jobId}) until the status is completed
4. Download the video from the content URL (GET /api/v1/videos/{jobId}/content)

API Usage

Submitting a Video Generation Request

1
import requests
2
import json
3
import time
4
5
url = "https://openrouter.ai/api/v1/videos"
6
headers = {
7
    "Authorization": f"Bearer {API_KEY_REF}",
8
    "Content-Type": "application/json"
9
}
10
11
payload = {
12
    "model": "{{MODEL}}",
13
    "prompt": "A golden retriever playing fetch on a sunny beach with waves crashing in the background"
14
}
15
16
# Step 1: Submit the generation request
17
response = requests.post(url, headers=headers, json=payload)
18
result = response.json()
19
20
job_id = result["id"]
21
polling_url = result["polling_url"]
22
print(f"Job submitted: {job_id}")
23
print(f"Status: {result['status']}")
24
25
# Step 2: Poll until completion
26
while True:
27
    time.sleep(30)  # Wait 30 seconds between polls
28
    poll_response = requests.get(polling_url, headers=headers)
29
    status = poll_response.json()
30
31
    print(f"Status: {status['status']}")
32
33
    if status["status"] == "completed":
34
        # Step 3: Download the video
35
        content_url = status["unsigned_urls"][0]
36
        video_response = requests.get(content_url)
37
        with open("output.mp4", "wb") as f:
38
            f.write(video_response.content)
39
        print("Video saved to output.mp4")
40
        break
41
    elif status["status"] == "failed":
42
        print(f"Generation failed: {status.get('error', 'Unknown error')}")
43
        break

Request Parameters

Supported Resolutions

• 480p
• 720p
• 1080p
• 1K
• 2K
• 4K

Supported Aspect Ratios

• 16:9 — Widescreen landscape
• 9:16 — Vertical/portrait
• 1:1 — Square
• 4:3 — Standard landscape
• 3:4 — Standard portrait
• 21:9 — Ultra-wide
• 9:21 — Ultra-tall

Using Images

There are two ways to provide images, each triggering a different generation mode:

• frame_images — Specifies first or last frame images for image-to-video generation. Each entry must include a frame_type of first_frame or last_frame.
• input_references — Provides style or content reference images for reference-to-video generation. The model uses these as visual guidance rather than exact frames.

If both fields are provided, frame_images takes precedence and the request is treated as image-to-video.

Image-to-Video (frame_images)

1
{
2
  "model": "alibaba/wan-2.7",
3
  "prompt": "A character walking through a forest",
4
  "frame_images": [
5
    {
6
      "type": "image_url",
7
      "image_url": {
8
        "url": "https://example.com/first-frame.png"
9
      },
10
      "frame_type": "first_frame"
11
    }
12
  ],
13
  "resolution": "1080p"
14
}

Reference-to-Video (input_references)

1
{
2
  "model": "alibaba/wan-2.7",
3
  "prompt": "A colossal solar flare beside a planet",
4
  "input_references": [
5
    {
6
      "type": "image_url",
7
      "image_url": {
8
        "url": "https://example.com/style-ref.png"
9
      }
10
    }
11
  ],
12
  "resolution": "1080p"
13
}

Provider-Specific Options

You can pass provider-specific options using the provider parameter. Options are keyed by provider slug, and only the options for the matched provider are forwarded:

1
{
2
  "model": "google/veo-3.1",
3
  "prompt": "A time-lapse of a flower blooming",
4
  "provider": {
5
    "options": {
6
      "google-vertex": {
7
        "parameters": {
8
          "personGeneration": "allow",
9
          "negativePrompt": "blurry, low quality"
10
        }
11
      }
12
    }
13
  }
14
}

Use the Video Models API to check which passthrough parameters each model supports via the allowed_passthrough_parameters field.

Response Format

Submit Response (202 Accepted)

When you submit a video generation request, you receive an immediate response with the job details:

1
{
2
  "id": "abc123",
3
  "polling_url": "https://openrouter.ai/api/v1/videos/abc123",
4
  "status": "pending"
5
}

Poll Response

When polling the job status, the response includes additional fields as the job progresses:

1
{
2
  "id": "abc123",
3
  "generation_id": "gen-1234567890-abcdef",
4
  "polling_url": "https://openrouter.ai/api/v1/videos/abc123",
5
  "status": "completed",
6
  "unsigned_urls": [
7
    "https://openrouter.ai/api/v1/videos/abc123/content?index=0"
8
  ],
9
  "usage": {
10
    "cost": 0.25,
11
    "is_byok": false
12
  }
13
}

Job Statuses

Downloading the Video

Once the job status is completed, the unsigned_urls array contains URLs to download the generated video content. You can also use the content endpoint directly:

$
curl "https://openrouter.ai/api/v1/videos/{jobId}/content?index=0" \
>
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
>
  --output video.mp4

The index query parameter defaults to 0 and can be used if the model generates multiple video outputs.

Webhooks

Instead of polling for job status, you can receive a webhook notification when a video generation job completes. There are two ways to configure a callback URL:

1. Per-request: Pass callback_url in the request body. This takes priority over the workspace default.
2. Workspace default: Set a default callback URL in your workspace settings. This applies to all video generation requests that don’t specify their own callback_url.

Webhook Payload

When the job completes (or fails), a POST request is sent to the callback URL with the job result:

1
{
2
  "id": "abc123",
3
  "status": "completed",
4
  "generation_id": "gen-xyz789",
5
  "model": "google/veo-3.1",
6
  "unsigned_urls": [
7
    "https://openrouter.ai/api/v1/videos/abc123/content?index=0"
8
  ],
9
  "usage": {
10
    "cost": 0.5,
11
    "is_byok": false
12
  }
13
}

Signing Secret

You can configure a signing secret in your workspace settings to verify that webhook payloads are authentically from OpenRouter. When a signing secret is configured, each webhook delivery includes an X-OpenRouter-Signature header.

The signature includes a timestamp and an HMAC hash:

X-OpenRouter-Signature: t=1234567890,v1=a1b2c3d4...

Verifying Signatures

To verify the signature on your webhook receiver:

1. Extract the timestamp (t) and signature hash (v1) from the header
2. Construct the signed payload: {timestamp},{raw_request_body} (joined with a comma)
3. Compute the HMAC-SHA256 of the signed payload using your signing secret as the key
4. Compare the hex-encoded result with the v1 value

1
import crypto from 'crypto';
2
3
const FIVE_MINUTES_IN_SECONDS = 300;
4
5
function verifyWebhookSignature(
6
  rawBody: string,
7
  signatureHeader: string,
8
  secret: string,
9
): boolean {
10
  const parts = signatureHeader.split(',');
11
  const timestamp = parts.find((p) => p.startsWith('t='))?.slice(2);
12
  const hash = parts.find((p) => p.startsWith('v1='))?.slice(3);
13
14
  if (!timestamp || !hash) {
15
    return false;
16
  }
17
18
  // Reject timestamps older than 5 minutes to prevent replay attacks
19
  const age = Math.floor(Date.now() / 1000) - Number(timestamp);
20
  if (Number.isNaN(age) || age > FIVE_MINUTES_IN_SECONDS) {
21
    return false;
22
  }
23
24
  const signedPayload = `${timestamp},${rawBody}`;
25
  const expected = crypto
26
    .createHmac('sha256', secret)
27
    .update(signedPayload)
28
    .digest('hex');
29
30
  if (expected.length !== hash.length) {
31
    return false;
32
  }
33
34
  return crypto.timingSafeEqual(
35
    Buffer.from(expected),
36
    Buffer.from(hash),
37
  );
38
}

Best Practices

• Detailed Prompts: Provide specific, descriptive prompts for better video quality. Include details about motion, camera angles, lighting, and scene composition
• Appropriate Resolution: Higher resolutions take longer to generate and cost more. Choose the resolution that fits your use case
• Polling Interval: Use a reasonable polling interval (e.g., 30 seconds) to avoid excessive API calls. Video generation typically takes 30 seconds to several minutes depending on the model and parameters
• Error Handling: Always check the job status for failed state and handle the error field appropriately
• Reference Images: When using reference images, ensure they are high quality and relevant to the desired video output

Zero Data Retention

Video generation is not eligible for Zero Data Retention (ZDR). Because video generation is asynchronous, the generated video output must be retained by the provider for a short period of time so that it can be retrieved after generation is complete. This temporary retention is inherent to the async polling workflow and cannot be bypassed.

If you have ZDR enforcement enabled (either via account settings or the per-request zdr parameter), video generation requests will not be routed.

Troubleshooting

Job stays in pending for a long time?

• Video generation can take several minutes depending on the model, resolution, and server load
• Continue polling at regular intervals

Generation failed?

• Check the error field in the poll response for details
• Verify the model supports video generation (output_modalities includes "video")
• Ensure your prompt is appropriate and within model guidelines
• Check that any reference images are accessible and in supported formats

Model not found?

• Use the Video Models API or the Models page to find available video generation models
• Verify the model slug is correct (e.g., google/veo-3.1)