VideoGeneration | OpenRouter Python SDK | OpenRouter

The Python SDK and docs are currently in beta. Report issues on GitHub.

Overview

Video Generation endpoints

Available Operations

generate - Submit a video generation request
get_generation - Poll video generation status
get_video_content - Download generated video content
list_videos_models - List all video generation models

generate

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

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.video_generation.generate(model="google/veo-3.1", prompt="A serene mountain landscape at sunset", aspect_ratio="16:9", duration=8, resolution="720p")
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description	Example
`model`	str	✔️	N/A
`prompt`	str	✔️	N/A
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`aspect_ratio`	Optional[components.AspectRatio]	➖	Aspect ratio of the generated video	16:9
`duration`	Optional[int]	➖	Duration of the generated video in seconds	8
`generate_audio`	Optional[bool]	➖	Whether to generate audio alongside the video. Defaults to true for models that support audio output, false otherwise.	true
`input_references`	List[components.ContentPartImage]	➖	Reference images to guide video generation
`provider`	Optional[components.Provider]	➖	Provider-specific passthrough configuration
`resolution`	Optional[components.Resolution]	➖	Resolution of the generated video	720p
`seed`	Optional[int]	➖	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`	Optional[str]	➖	Exact pixel dimensions of the generated video in “WIDTHxHEIGHT” format (e.g. “1280x720”). Interchangeable with resolution + aspect_ratio.	1280x720
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.VideoGenerationResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.PaymentRequiredResponseError	402	application/json
errors.NotFoundResponseError	404	application/json
errors.TooManyRequestsResponseError	429	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get_generation

Returns job status and content URLs when completed

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.video_generation.get_generation(job_id="job-abc123")
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description	Example
`job_id`	str	✔️	N/A	job-abc123
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.VideoGenerationResponse

Errors

Error Type	Status Code	Content Type
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

get_video_content

Streams the generated video content from the upstream provider

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.video_generation.get_video_content(job_id="job-abc123", index=0)
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description	Example
`job_id`	str	✔️	N/A	job-abc123
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`index`	OptionalNullable[int]	➖	N/A	0
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

httpx.Response

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.UnauthorizedResponseError	401	application/json
errors.NotFoundResponseError	404	application/json
errors.InternalServerResponseError	500	application/json
errors.BadGatewayResponseError	502	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/

list_videos_models

Returns a list of all available video generation models and their properties

Example Usage

1 from openrouter import OpenRouter
2 import os
3 
4 with OpenRouter(
5     http_referer="<value>",
6     x_open_router_title="<value>",
7     x_open_router_categories="<value>",
8     api_key=os.getenv("OPENROUTER_API_KEY", ""),
9 ) as open_router:
10 
11     res = open_router.video_generation.list_videos_models()
12 
13     # Handle response
14     print(res)

Parameters

Parameter	Type	Required	Description
`http_referer`	Optional[str]	➖	The app identifier should be your app’s URL and is used as the primary identifier for rankings. This is used to track API usage per application.
`x_open_router_title`	Optional[str]	➖	The app display name allows you to customize how your app appears in OpenRouter’s dashboard.
`x_open_router_categories`	Optional[str]	➖	Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings.
`retries`	Optional[utils.RetryConfig]	➖	Configuration to override the default retry behavior of the client.

Response

components.VideoModelsListResponse

Errors

Error Type	Status Code	Content Type
errors.BadRequestResponseError	400	application/json
errors.InternalServerResponseError	500	application/json
errors.OpenRouterDefaultError	4XX, 5XX	/