Overview
Video Generation endpointsAvailable 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 statusExample Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.video_generation.generate(model="google/veo-3.1", aspect_ratio="16:9", duration=8, prompt="A serene mountain landscape at sunset", resolution="720p")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
model | str | :heavy_check_mark: | N/A | |
http_referer | Optional[str] | :heavy_minus_sign: | 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] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
aspect_ratio | Optional[components.VideoGenerationRequestAspectRatio] | :heavy_minus_sign: | Aspect ratio of the generated video | 16:9 |
callback_url | Optional[str] | :heavy_minus_sign: | URL to receive a webhook notification when the video generation job completes. Overrides the workspace-level default callback URL if set. Must be HTTPS. | https://example.com/webhook |
creativity | Optional[int] | :heavy_minus_sign: | Creativity level for video upscaling models only. This parameter is not supported by video generation models. | 1 |
duration | Optional[int] | :heavy_minus_sign: | Duration of the generated video in seconds | 8 |
frame_images | List[components.FrameImage] | :heavy_minus_sign: | 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 | Optional[bool] | :heavy_minus_sign: | Whether to generate audio alongside the video. Defaults to the endpoint’s generate_audio capability flag, false if not set. | true |
input_references | List[components.InputReference] | :heavy_minus_sign: | Reference assets to guide video generation. Accepts image, audio, and video references. Audio and video references are only honored by providers that support them (including BytePlus Seedance generation 2 and newer); other providers use image references and ignore the rest. | |
previous_job_id | Optional[str] | :heavy_minus_sign: | 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. | gen-vid-1789493115-a1B2c3D4e5F6g7H8i9J0 |
prompt | Optional[str] | :heavy_minus_sign: | Text prompt describing the video to generate. Optional for models that support generating a video from image input alone; required by all other models. | A serene mountain landscape at sunset |
provider | Optional[components.VideoGenerationRequestProvider] | :heavy_minus_sign: | Provider-specific passthrough configuration | |
resolution | Optional[components.VideoGenerationRequestResolution] | :heavy_minus_sign: | Resolution of the generated video | 720p |
seed | Optional[int] | :heavy_minus_sign: | 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_id | Optional[str] | :heavy_minus_sign: | 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. | session-1234 |
size | Optional[str] | :heavy_minus_sign: | Exact pixel dimensions of the generated video in “WIDTHxHEIGHT” format (e.g. “1280x720”). Interchangeable with resolution + aspect_ratio. | 1280x720 |
trace | Optional[components.TraceConfig] | :heavy_minus_sign: | Metadata for observability and tracing. Known keys (trace_id, trace_name, span_name, generation_name, parent_span_id) have special handling. Additional keys are passed through as custom metadata to configured broadcast destinations. | { “trace_id”: “trace-abc123”, “trace_name”: “my-app-trace” } |
upscale_factor | Optional[float] | :heavy_minus_sign: | Upscale factor for video upscaling models only. This parameter is not supported by video generation models. | 2 |
user | Optional[str] | :heavy_minus_sign: | A unique identifier representing your end-user. Forwarded to Broadcast and private logging as the end-user id; never sent to the provider. | user-1234 |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.VideoGenerationResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.PaymentRequiredResponseError | 402 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.PayloadTooLargeResponseError | 413 | 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 completedExample Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.video_generation.get_generation(job_id="job-abc123")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
job_id | str | :heavy_check_mark: | N/A | job-abc123 |
http_referer | Optional[str] | :heavy_minus_sign: | 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] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.VideoGenerationResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | 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 providerExample Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.video_generation.get_video_content(job_id="job-abc123", index=0)
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
job_id | str | :heavy_check_mark: | N/A | job-abc123 |
http_referer | Optional[str] | :heavy_minus_sign: | 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] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. | |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. | |
index | OptionalNullable[int] | :heavy_minus_sign: | N/A | 0 |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
httpx.ResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.UnauthorizedResponseError | 401 | application/json |
| errors.ForbiddenResponseError | 403 | application/json |
| errors.NotFoundResponseError | 404 | application/json |
| errors.ConflictResponseError | 409 | application/json |
| errors.GoneResponseError | 410 | 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 propertiesExample Usage
from openrouter import OpenRouter
import os
with OpenRouter(
http_referer="<value>",
x_open_router_title="<value>",
x_open_router_categories="<value>",
api_key=os.getenv("OPENROUTER_API_KEY", ""),
) as open_router:
res = open_router.video_generation.list_videos_models()
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
http_referer | Optional[str] | :heavy_minus_sign: | 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] | :heavy_minus_sign: | The app display name allows you to customize how your app appears in OpenRouter’s dashboard. |
x_open_router_categories | Optional[str] | :heavy_minus_sign: | Comma-separated list of app categories (e.g. “cli-agent,cloud-agent”). Used for marketplace rankings. |
retries | Optional[utils.RetryConfig] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
components.VideoModelsListResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.BadRequestResponseError | 400 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |