Use Provider-Specific Video Options
Use Provider-Specific Video Options
Inspect allowed passthrough parameters and send provider-specific video controls safely
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_KEYonly 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:
Example output:
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:
Metadata assertion output:
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:
The submit call returns the job fields immediately. In the QA run, the submitted job later completed and downloaded with this final summary:
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:
Request shape for google/veo-3.1-lite:
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.