Images - OpenRouter | Documentation

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

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.ImageGenerationRequestProvider]	:heavy_minus_sign:	Provider-specific passthrough configuration
`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. 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]	: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.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

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.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

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.ImageModelEndpointsResponse

Errors

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

​Overview

​Available Operations

​generate

​Example Usage

​Parameters

​Response

​Errors

​list_models

​Example Usage

​Parameters

​Response

​Errors

​list_model_endpoints

​Example Usage

​Parameters

​Response

​Errors

Overview

Available Operations

generate

Example Usage

Parameters

Response

Errors

list_models

Example Usage

Parameters

Response

Errors

list_model_endpoints

Example Usage

Parameters

Response

Errors