For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
ModelsChatRankingsDocs
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
DocsAPI ReferenceClient SDKsAgent SDKCookbookChangelog
  • Get Started
    • Quickstart: Build a Chat App
    • Enterprise Quickstart
    • Free Models Router
  • Working with Coding Agents
    • Automatic Code Review
    • Claude Code
    • Claude Desktop
    • Codex CLI
    • Cursor
    • Hermes Agent
    • Junie CLI
    • MCP Servers
    • OpenClaw 🦞
    • OpenCode
  • Building Agents
    • Add Human-in-the-Loop Controls
    • Build a Long-Horizon Agent
    • Build Your Own Agent TUI
    • Build Your Own Headless Agent
  • Video Generation
    • Choose a Video Generation Model
    • Generate and Download a Video from Text
    • Get Video Results with Webhooks
    • Guide a Video with Reference Images
    • Turn an Image into a Video
    • Use Provider-Specific Video Options
  • Evaluate & Optimize
    • Distillation
    • RAG with Embeddings & Rerank
    • Red Teaming
  • Administration
    • Activity Export
    • API Key Rotation
    • Crypto API
    • Organization Management
    • Usage Accounting
    • User Tracking
LogoLogo
ModelsChatRankingsDocs
On this page
  • Before you start
  • Step 1: Inspect allowed passthrough parameters
  • Step 2: Add provider options to the video request
  • Step 3: Keep a fallback without passthrough options
  • Check your work
Video Generation

Use Provider-Specific Video Options

Inspect allowed passthrough parameters and send provider-specific video controls safely

Was this page helpful?
Previous

Distillation

Ensure compliance with provider and model creator policies for distillation
Next
Built with

Use this guide when you need to add video model controls that are not part of OpenRouter’s normalized video schema.

By the end, your implementation should inspect a model’s allowed passthrough parameters and send one through provider.options.

For reusable agent knowledge across projects, install the openrouter-video skill.

Before you start

You need:

  • Node.js 20 or newer
  • An OpenRouter API key available as OPENROUTER_API_KEY only when you submit the video job
  • A target video model for the provider-specific options you want to send

If you are not already targeting a specific provider model, read Choose a Video Generation Model so you can select one based on your clip duration, output shape, input type, audio, provider controls, and cost requirements.

Use the API reference pages as the source of truth for exact fields:

  • Create video generation request
  • List video generation models
  • TypeScript SDK video generation reference

Provider-specific options can change by model and provider. Always check allowed_passthrough_parameters before relying on one.

Submitting POST /api/v1/videos starts a real video generation job and may spend OpenRouter credits.

Step 1: Inspect allowed passthrough parameters

Start by reading allowed_passthrough_parameters from the selected model. This keeps provider-specific controls behind a model metadata check instead of hard-coding unsupported request keys.

Example metadata check:

1const response = await fetch("https://openrouter.ai/api/v1/videos/models");
2
3if (!response.ok) {
4 throw new Error(await response.text());
5}
6
7const { data } = await response.json();
8const models = data;
9const veo = models.find(
10 (model) => model.id === "google/veo-3.1-lite",
11);
12
13if (!veo) {
14 throw new Error("google/veo-3.1-lite was not found in the video model list.");
15}
16
17console.log(veo.allowed_passthrough_parameters);

Example output:

1[
2 "personGeneration",
3 "aspectRatio",
4 "negativePrompt",
5 "conditioningScale",
6 "enhancePrompt"
7]

For example, google/veo-3.1-lite may expose passthrough controls such as negativePrompt, enhancePrompt, personGeneration, or conditioningScale. OpenRouter lists supported parameter names; check the provider docs for valid values when a parameter has an enum.

Before submitting a paid job, assert that every passthrough key you plan to send is allowed for the selected model:

1const providerParameters = {
2 negativePrompt: "blurry, low quality, distorted petals",
3 enhancePrompt: true,
4};
5
6const unsupportedParameters = Object.keys(providerParameters).filter(
7 (key) => !veo.allowed_passthrough_parameters?.includes(key),
8);
9
10if (unsupportedParameters.length > 0) {
11 throw new Error(
12 `Unsupported passthrough parameters: ${unsupportedParameters.join(", ")}`,
13 );
14}
15
16console.log("All provider parameters are supported.");

Metadata assertion output:

All provider parameters are supported.

Step 2: Add provider options to the video request

Provider options are keyed by provider slug. Only the options for the matched provider are forwarded. For the Google Vertex video endpoint, use the google-vertex provider slug.

Example request shape:

1const apiKey = process.env.OPENROUTER_API_KEY;
2
3if (!apiKey) {
4 throw new Error("Set OPENROUTER_API_KEY before submitting a video job.");
5}
6
7const response = await fetch("https://openrouter.ai/api/v1/videos", {
8 method: "POST",
9 headers: {
10 Authorization: `Bearer ${apiKey}`,
11 "Content-Type": "application/json",
12 },
13 body: JSON.stringify({
14 model: "google/veo-3.1-lite",
15 prompt:
16 "A 4-second time-lapse of a white orchid blooming on a dark tabletop, macro lens, gentle studio light",
17 duration: 4,
18 resolution: "720p",
19 aspect_ratio: "16:9",
20 generate_audio: false,
21 provider: {
22 options: {
23 "google-vertex": {
24 parameters: providerParameters,
25 },
26 },
27 },
28 }),
29});
30
31if (!response.ok) {
32 throw new Error(await response.text());
33}
34
35console.log(await response.json());

The submit call returns the job fields immediately. In the QA run, the submitted job later completed and downloaded with this final summary:

1{
2 "id": "2hAwXrT31ZpCI8MsjBEe",
3 "status": "completed",
4 "polling_url": "https://openrouter.ai/api/v1/videos/2hAwXrT31ZpCI8MsjBEe",
5 "downloaded_path": "provider-options.mp4",
6 "downloaded_bytes": 794331
7}

To wait for the playable MP4, use the polling and download helper from Generate and Download a Video from Text after submission.

Step 3: Keep a fallback without passthrough options

If your app can route across multiple video models, keep the normalized request separate from model-specific options:

1const baseRequest = {
2 prompt: "A short cinematic product shot of a white orchid blooming",
3 duration: 4,
4 resolution: "720p",
5 aspect_ratio: "16:9",
6};
7
8const selectedModel = {
9 id: "google/veo-3.1-lite",
10};
11
12const requestBody =
13 selectedModel.id === "google/veo-3.1-lite"
14 ? {
15 ...baseRequest,
16 model: selectedModel.id,
17 provider: {
18 options: {
19 "google-vertex": {
20 parameters: {
21 negativePrompt: "blurry, low quality",
22 },
23 },
24 },
25 },
26 }
27 : {
28 ...baseRequest,
29 model: selectedModel.id,
30 };

Request shape for google/veo-3.1-lite:

1{
2 "prompt": "A short cinematic product shot of a white orchid blooming",
3 "duration": 4,
4 "resolution": "720p",
5 "aspect_ratio": "16:9",
6 "model": "google/veo-3.1-lite",
7 "provider": {
8 "options": {
9 "google-vertex": {
10 "parameters": {
11 "negativePrompt": "blurry, low quality"
12 }
13 }
14 }
15 }
16}

Check your work

The metadata assertion should pass before you submit a job. If you submit the request, it should return a video job. If the provider option is invalid for the selected model, remove it or re-check the current allowed_passthrough_parameters list. To verify the final output, poll the returned polling_url until completed, then download the MP4.