Images - Python SDK
Images - Python SDK
Images method reference
The Python SDK and docs are currently in beta. Report issues on GitHub.
Overview
Images endpoints
Available Operations
- generate - Generate an image
- list_models - List image generation models
- list_model_endpoints - List endpoints for an image model
generate
Generates an image from a text prompt via the image generation router
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.images.generate(model="bytedance-seed/seedream-4.5", prompt="a red panda astronaut floating in space, studio lighting") 12 13 with res as event_stream: 14 for event in event_stream: 15 # handle event 16 print(event, flush=True)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
model | str | ✔️ | The image generation model to use | bytedance-seed/seedream-4.5 |
prompt | str | ✔️ | Text description of the desired image | a red panda astronaut floating in space, studio lighting |
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.ImageGenerationRequestAspectRatio] | ➖ | Normalized aspect ratio of the generated image. Providers clamp to their supported subset. | 16:9 |
background | Optional[components.ImageGenerationRequestBackground] | ➖ | Background treatment. transparent requires an output_format that supports alpha (png or webp). | auto |
input_references | List[components.ContentPartImage] | ➖ | Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. | |
n | Optional[int] | ➖ | Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. | 1 |
output_compression | Optional[int] | ➖ | Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. | 100 |
output_format | Optional[components.ImageGenerationRequestOutputFormat] | ➖ | Encoding of the returned image bytes. | png |
provider | Optional[components.ImageGenerationRequestProvider] | ➖ | Provider-specific passthrough configuration | |
quality | Optional[components.ImageGenerationRequestQuality] | ➖ | Rendering quality. Providers without a quality knob ignore this. | high |
resolution | Optional[components.ImageGenerationRequestResolution] | ➖ | Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. | 2K |
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] | ➖ | Optional. A convenience shorthand for output dimensions — pass a tier (“2K”, “4K”) or explicit pixels (“2048x2048”) and we normalize it to the right dimensions for the chosen provider. Interchangeable with resolution + aspect_ratio; use those directly for enumerated, per-model discoverable values. Conflicting size + resolution/aspect_ratio is rejected. | 2K |
stream | Optional[bool] | ➖ | If true, partial images are streamed as SSE events as they become available. Only supported by providers with native streaming (currently OpenAI). Non-streaming providers ignore this flag and return a buffered response. | |
retries | Optional[utils.RetryConfig] | ➖ | Configuration to override the default retry behavior of the client. |
Response
operations.CreateImagesResponse
Errors
| 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.TooManyRequestsResponseError | 429 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.BadGatewayResponseError | 502 | application/json |
| errors.EdgeNetworkTimeoutResponseError | 524 | application/json |
| errors.ProviderOverloadedResponseError | 529 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
list_models
Lists every image generation model with its top-level supported-parameter superset and a URL to its full per-endpoint records.
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.images.list_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.ImageModelsListResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |
list_model_endpoints
Returns the full per-endpoint records for an image model: each endpoint’s definitive supported parameters, pricing, and passthrough allowlist.
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.images.list_model_endpoints(author="bytedance-seed", slug="seedream-4.5") 12 13 # Handle response 14 print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
author | str | ✔️ | Model author/organization | bytedance-seed |
slug | str | ✔️ | Model slug | seedream-4.5 |
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.ImageModelEndpointsResponse
Errors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |