Overview
Images endpointsAvailable 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 routerExample 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.images.generate(model="bytedance-seed/seedream-4.5", prompt="a red panda astronaut floating in space, studio lighting")
with res as event_stream:
for event in event_stream:
# handle event
print(event, flush=True)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
model | str | :heavy_check_mark: | The image generation model to use | bytedance-seed/seedream-4.5 |
prompt | str | :heavy_check_mark: | Text description of the desired image | a red panda astronaut floating in space, studio lighting |
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.ImageGenerationRequestAspectRatio] | :heavy_minus_sign: | Normalized aspect ratio of the generated image. Providers clamp to their supported subset. | 16:9 |
background | Optional[components.ImageGenerationRequestBackground] | :heavy_minus_sign: | Background treatment. transparent requires an output_format that supports alpha (png or webp). | auto |
input_references | List[components.ContentPartImage] | :heavy_minus_sign: | Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs. | |
n | Optional[int] | :heavy_minus_sign: | Number of images to generate (1-10). Providers that only support single-image generation reject n > 1. | 1 |
output_compression | Optional[int] | :heavy_minus_sign: | Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob. | 100 |
output_format | Optional[components.ImageGenerationRequestOutputFormat] | :heavy_minus_sign: | Encoding of the returned image bytes. Most models produce raster formats (png, jpeg, webp). SVG is supported by vectorization models (e.g. Quiver) — the SVG markup is UTF-8 base64-encoded in b64_json. | png |
provider | Optional[components.ImageGenerationProviderPreferences] | :heavy_minus_sign: | Provider routing preferences and provider-specific passthrough configuration. | { “allow_fallbacks”: false, “only”: [ “google-ai-studio” ] } |
quality | Optional[components.ImageGenerationRequestQuality] | :heavy_minus_sign: | Rendering quality. Providers without a quality knob ignore this. | high |
resolution | Optional[components.ImageGenerationRequestResolution] | :heavy_minus_sign: | Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider. | 2K |
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. | |
size | Optional[str] | :heavy_minus_sign: | 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. A tier size is equivalent to setting resolution and combines with aspect_ratio. An explicit pixel size is authoritative: a mismatched resolution or aspect_ratio alongside it is rejected with a 400. | 2K |
stream | Optional[bool] | :heavy_minus_sign: | 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] | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
Response
operations.CreateImagesResponseErrors
| 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.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
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.images.list_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.ImageModelsListResponseErrors
| 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
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.images.list_model_endpoints(author="bytedance-seed", slug="seedream-4.5")
# Handle response
print(res)
Parameters
| Parameter | Type | Required | Description | Example |
|---|---|---|---|---|
author | str | :heavy_check_mark: | Model author/organization | bytedance-seed |
slug | str | :heavy_check_mark: | Model slug | seedream-4.5 |
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.ImageModelEndpointsResponseErrors
| Error Type | Status Code | Content Type |
|---|---|---|
| errors.NotFoundResponseError | 404 | application/json |
| errors.InternalServerResponseError | 500 | application/json |
| errors.OpenRouterDefaultError | 4XX, 5XX | */* |