Video Generation

Submit a video generation request

Changed on

Submits a video generation request and returns a polling URL to check status

post/videos

Request

  • Base URL: https://openrouter.ai/api/v1
  • URL: https://openrouter.ai/api/v1/videos
  • Auth: HTTP bearer

Request body

aspect_ratio'16:9' | '9:16' | '1:1' | '4:3' | '3:4' | '3:2' | '2:3' | '21:9' | '9:21'

Aspect ratio of the generated video

callback_urlstring uri

URL to receive a webhook notification when the video generation job completes. Overrides the workspace-level default callback URL if set. Must be HTTPS.

creativityinteger

Creativity level for video upscaling models only. This parameter is not supported by video generation models.

durationinteger

Duration of the generated video in seconds

generate_audioboolean

Whether to generate audio alongside the video. Defaults to the endpoint's generate_audio capability flag, false if not set.

modelstring required
previous_job_idstring

ID of a completed video job to edit or extend, as returned by the submit response. The new job runs on the same model and endpoint that produced the previous one. Only models that support continuation accept this field.

promptstring

Text prompt describing the video to generate. Optional for models that support generating a video from image input alone; required by all other models.

resolution'360p' | '480p' | '720p' | '768p' | '1080p' | '1K' | '2K' | '4K'

Resolution of the generated video

seedinteger

If specified, the generation will sample deterministically, such that repeated requests with the same seed and parameters should return the same result. Determinism is not guaranteed for all providers.

session_idstring

A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.

sizestring

Exact pixel dimensions of the generated video in "WIDTHxHEIGHT" format (e.g. "1280x720"). Interchangeable with resolution + aspect_ratio.

upscale_factornumber

Upscale factor for video upscaling models only. This parameter is not supported by video generation models.

userstring

A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider.

Example request

{
  "aspect_ratio": "16:9",
  "duration": 8,
  "model": "google/veo-3.1",
  "prompt": "A serene mountain landscape at sunset",
  "resolution": "720p"
}

Response

Video generation request accepted

errorstring
expires_atinteger

Unix timestamp in seconds when OpenRouter's stored copy of the outputs stops being available. Present only when that copy exists.

generation_idstring

The generation ID associated with this video generation job. Available once the job has been processed.

idstring required

The video job ID, in the gen-vid-<timestamp>-<20 alphanumerics> generation ID format. Pass it as previous_job_id to continue the generation.

polling_urlstring required
status'pending' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'expired' required
unsigned_urlsstring[]

OpenRouter content URLs for each output. They need your API key in the Authorization header and keep working for as long as the output is available.

urlsstring[]

Signed download URLs for OpenRouter's stored copy of each output, usable without an API key until expires_at. Anyone holding a URL can download that output until it expires, so treat it like a secret. Present only when the stored copy exists.

Example response

{
  "generation_id": "gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt",
  "id": "gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt",
  "polling_url": "/api/v1/videos/gen-vid-1789480874-Ab3dEf9hIjKlMnOpQrSt",
  "status": "pending"
}

Changes