mirror of
https://github.com/wassname/openrouter-python-sdk-retry-errors.git
synced 2026-07-29 11:23:49 +08:00
177 lines
49 KiB
Plaintext
177 lines
49 KiB
Plaintext
---
|
|
title: "Images"
|
|
description: "Images endpoints"
|
|
---
|
|
|
|
## Overview
|
|
|
|
Images endpoints
|
|
|
|
### Available Operations
|
|
|
|
* [generate](#generate) - Generate an image
|
|
* [list_models](#list_models) - List image generation models
|
|
* [list_model_endpoints](#list_model_endpoints) - List endpoints for an image model
|
|
|
|
## generate
|
|
|
|
Generates an image from a text prompt via the image generation router
|
|
|
|
### Example Usage
|
|
|
|
```python
|
|
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.<br/>This is used to track API usage per application.<br/> | |
|
|
| `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.<br/> | |
|
|
| `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.<br/> | |
|
|
| `aspect_ratio` | [Optional[components.ImageGenerationRequestAspectRatio]](../../components/imagegenerationrequestaspectratio.mdx) | :heavy_minus_sign: | Normalized aspect ratio of the generated image. Providers clamp to their supported subset. | 16:9 |
|
|
| `background` | [Optional[components.ImageGenerationRequestBackground]](../../components/imagegenerationrequestbackground.mdx) | :heavy_minus_sign: | Background treatment. `transparent` requires an output_format that supports alpha (png or webp). | auto |
|
|
| `input_references` | List[[components.ContentPartImage](../../components/contentpartimage.mdx)] | :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]](../../components/imagegenerationrequestoutputformat.mdx) | :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]](../../components/imagegenerationrequestprovider.mdx) | :heavy_minus_sign: | Provider-specific passthrough configuration | |
|
|
| `quality` | [Optional[components.ImageGenerationRequestQuality]](../../components/imagegenerationrequestquality.mdx) | :heavy_minus_sign: | Rendering quality. Providers without a quality knob ignore this. | high |
|
|
| `resolution` | [Optional[components.ImageGenerationRequestResolution]](../../components/imagegenerationrequestresolution.mdx) | :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]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
|
|
|
|
### Response
|
|
|
|
**[operations.CreateImagesResponse](../../operations/createimagesresponse.mdx)**
|
|
|
|
### 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
|
|
|
|
```python
|
|
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.<br/>This is used to track API usage per application.<br/> |
|
|
| `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.<br/> |
|
|
| `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.<br/> |
|
|
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. |
|
|
|
|
### Response
|
|
|
|
**[components.ImageModelsListResponse](../../components/imagemodelslistresponse.mdx)**
|
|
|
|
### 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
|
|
|
|
```python
|
|
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.<br/>This is used to track API usage per application.<br/> | |
|
|
| `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.<br/> | |
|
|
| `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.<br/> | |
|
|
| `retries` | [Optional[utils.RetryConfig]](../../models/utils/retryconfig.mdx) | :heavy_minus_sign: | Configuration to override the default retry behavior of the client. | |
|
|
|
|
### Response
|
|
|
|
**[components.ImageModelEndpointsResponse](../../components/imagemodelendpointsresponse.mdx)**
|
|
|
|
### Errors
|
|
|
|
| Error Type | Status Code | Content Type |
|
|
| ---------------------------------- | ---------------------------------- | ---------------------------------- |
|
|
| errors.NotFoundResponseError | 404 | application/json |
|
|
| errors.InternalServerResponseError | 500 | application/json |
|
|
| errors.OpenRouterDefaultError | 4XX, 5XX | \*/\* | |