Skip to main content
POST
/
videos
Submit a video generation request
curl --request POST \
  --url https://openrouter.ai/api/v1/videos \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "aspect_ratio": "16:9",
  "duration": 8,
  "model": "google/veo-3.1",
  "prompt": "A serene mountain landscape at sunset",
  "resolution": "720p"
}
'
{
  "generation_id": "gen-xyz789",
  "id": "job-abc123",
  "polling_url": "/api/v1/videos/job-abc123",
  "status": "pending"
}

Authorizations

​
Authorization
string
header
required

API key as bearer token in Authorization header

Body

application/json
​
model
string
required
​
prompt
string
required
​
aspect_ratio
enum<string>

Aspect ratio of the generated video

Available options:
16:9,
9:16,
1:1,
4:3,
3:4,
3:2,
2:3,
21:9,
9:21
Example:

"16:9"

​
callback_url
string<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.

Example:

"https://example.com/webhook"

​
duration
integer

Duration of the generated video in seconds

Required range: x >= 1
Example:

8

​
frame_images
object[]

Images to use as the first and/or last frame of the generated video. Each image must specify a frame_type of first_frame or last_frame.

​
generate_audio
boolean

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

Example:

true

​
input_references
object[]

Reference assets to guide video generation. Accepts image, audio, and video references. Audio and video references are only honored by providers that support them (currently BytePlus Seedance 2.0); other providers use image references and ignore the rest.

A reference asset used to guide video generation. Image references are supported by all providers; audio and video references are only honored by providers that support them (currently BytePlus Seedance 2.0).

Example:
{
  "image_url": { "url": "https://example.com/image.png" },
  "type": "image_url"
}
​
provider
object

Provider-specific passthrough configuration

​
resolution
enum<string>

Resolution of the generated video

Available options:
480p,
720p,
1080p,
1K,
2K,
4K
Example:

"720p"

​
seed
integer

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.

​
size
string

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

Example:

"1280x720"

Response

Video generation request accepted

​
id
string
required
​
polling_url
string
required
​
status
enum<string>
required
Available options:
pending,
in_progress,
completed,
failed,
cancelled,
expired
​
error
string
​
generation_id
string

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

​
unsigned_urls
string[]
​
usage
object

Usage and cost information for the video generation. Available once the job has completed.

Example:
{ "cost": 0.5, "is_byok": false }