Image Generation

OpenRouter provides a dedicated Image API for generating images from text prompts (and optional reference images). The API covers model discovery, per-endpoint capabilities, and generation. You can browse available models and pricing on the models page filtered by image output.

Model Discovery

Via the Image Models API

The dedicated image models endpoint lists every available image model with its capabilities:

$
curl "https://openrouter.ai/api/v1/images/models"

Each entry in the data array includes:

1
{
2
  "data": [
3
    {
4
      "id": "bytedance-seed/seedream-4.5",
5
      "name": "Seedream 4.5",
6
      "description": "A text-to-image model.",
7
      "created": 1692901234,
8
      "architecture": {
9
        "input_modalities": ["text", "image"],
10
        "output_modalities": ["image"]
11
      },
12
      "supported_parameters": {
13
        "resolution": { "type": "enum", "values": ["1K", "2K", "4K"] },
14
        "seed": { "type": "boolean" }
15
      },
16
      "supports_streaming": false,
17
      "endpoints": "/api/v1/images/models/bytedance-seed/seedream-4.5/endpoints"
18
    }
19
  ]
20
}

Per-Endpoint Records

Each model may be served by multiple providers. To see the definitive capabilities, pricing, and passthrough options per endpoint:

$
curl "https://openrouter.ai/api/v1/images/models/bytedance-seed/seedream-4.5/endpoints"

1
{
2
  "id": "bytedance-seed/seedream-4.5",
3
  "endpoints": [
4
    {
5
      "provider_name": "Bytedance",
6
      "provider_slug": "bytedance",
7
      "provider_tag": "bytedance",
8
      "supported_parameters": {
9
        "resolution": { "type": "enum", "values": ["1K", "2K", "4K"] },
10
        "seed": { "type": "boolean" }
11
      },
12
      "allowed_passthrough_parameters": [],
13
      "supports_streaming": false,
14
      "pricing": [
15
        { "billable": "output_image", "unit": "image", "cost_usd": 0.05 }
16
      ]
17
    }
18
  ]
19
}

Capability Descriptors

The supported_parameters map uses typed descriptors to describe what each request field accepts:

An absent key means the parameter is unsupported by that endpoint.

Via the Models API

You can also discover image models through the general Models API:

$
curl "https://openrouter.ai/api/v1/models?output_modalities=image"

On the Models Page

Visit the Models page and filter by output modalities to find models with image generation capabilities.

API Usage

Send a POST request to /api/v1/images with the model and prompt:

1
import requests
2
import json
3
4
url = "https://openrouter.ai/api/v1/images"
5
headers = {
6
    "Authorization": f"Bearer {API_KEY_REF}",
7
    "Content-Type": "application/json"
8
}
9
10
payload = {
11
    "model": "{{MODEL}}",
12
    "prompt": "a red panda astronaut floating in space, studio lighting"
13
}
14
15
response = requests.post(url, headers=headers, json=payload)
16
result = response.json()
17
18
for image in result["data"]:
19
    # image["b64_json"] contains the base64-encoded image
20
    print(f"Generated image ({len(image['b64_json'])} chars)")

Response Format

1
{
2
  "created": 1748372400,
3
  "data": [
4
    {
5
      "b64_json": "<base64-encoded-image>"
6
    }
7
  ],
8
  "usage": {
9
    "prompt_tokens": 0,
10
    "completion_tokens": 4175,
11
    "total_tokens": 4175,
12
    "cost": 0.04
13
  }
14
}

Images are returned as base64-encoded bytes. The usage field reports token counts and cost when available.

Image Configuration Options

Resolution and Aspect Ratio

Control output dimensions with resolution, aspect_ratio, or the convenience size shorthand:

1
{
2
  "model": "bytedance-seed/seedream-4.5",
3
  "prompt": "a landscape photo",
4
  "resolution": "2K",
5
  "aspect_ratio": "16:9"
6
}

• resolution — normalized tier (512, 1K, 2K, 4K). Concrete pixel dimensions are derived per-provider.
• aspect_ratio — normalized ratio. Pass auto to let the provider choose. Common values include 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, and extended ratios like 1:2, 2:1, 1:4, 4:1, 1:8, 8:1, 9:21, 21:9. Providers clamp to their supported subset — check the model’s supported_parameters for accepted values.
• size — convenience shorthand. Pass a tier ("2K") or explicit pixels ("2048x2048") and it gets normalized for the provider. Interchangeable with resolution + aspect_ratio; conflicting values are rejected.

Check the model’s supported_parameters to see which values each endpoint accepts.

Quality and Output Format

1
{
2
  "model": "openai/gpt-image-1",
3
  "prompt": "a product photo",
4
  "quality": "high",
5
  "output_format": "png",
6
  "background": "transparent"
7
}

• quality — auto, low, medium, or high. Providers without a quality knob ignore this.
• output_format — png, jpeg, or webp.
• background — auto, transparent, or opaque. transparent requires an alpha-capable format (png or webp).
• output_compression — 0–100 for webp/jpeg. Ignored for png.

Multiple Images

Request up to 10 images per call with n:

1
{
2
  "model": "openai/gpt-image-1",
3
  "prompt": "a cute cat",
4
  "n": 4
5
}

Not all providers support n > 1. Check the model’s supported_parameters for availability.

Image-to-Image (Reference Images)

Pass reference images to guide generation via input_references:

1
{
2
  "model": "openai/gpt-image-1",
3
  "prompt": "make this scene look like a watercolor painting",
4
  "input_references": [
5
    {
6
      "type": "image_url",
7
      "image_url": {
8
        "url": "https://example.com/photo.jpg"
9
      }
10
    }
11
  ]
12
}

Reference images can be HTTP(S) URLs or base64 data URLs. The number of references accepted varies by provider.

Provider-Specific Options

Pass provider-specific parameters through provider.options, keyed by the provider slug from the endpoints API:

1
{
2
  "model": "black-forest-labs/flux.2-pro",
3
  "prompt": "a dramatic portrait",
4
  "provider": {
5
    "options": {
6
      "black-forest-labs": {
7
        "steps": 40,
8
        "guidance": 3
9
      }
10
    }
11
  }
12
}

The allowed_passthrough_parameters field in each endpoint record lists which keys are accepted.

Streaming Image Generation

Models that support native SSE streaming (supports_streaming: true in the discovery API) can return partial images as they’re generated:

1
{
2
  "model": "openai/gpt-image-1",
3
  "prompt": "a detailed landscape",
4
  "stream": true
5
}

The response is an SSE stream with three event types:

Partial image — emitted as each partial render becomes available:

data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"<base64>"}

Completed — emitted when the final image is ready:

data: {"type":"image_generation.completed","b64_json":"<base64>","created":1748372400,"usage":{"prompt_tokens":16,"completion_tokens":272,"total_tokens":288,"cost":0.011}}

The usage object in the completed event includes cost (USD), matching the buffered response shape.

Error — emitted if generation fails mid-stream:

data: {"type":"error","error":{"message":"Generation failed","code":"server_error"}}

The stream terminates with data: [DONE].

1
import requests
2
3
url = "https://openrouter.ai/api/v1/images"
4
headers = {
5
    "Authorization": f"Bearer {API_KEY_REF}",
6
    "Content-Type": "application/json"
7
}
8
9
response = requests.post(url, headers=headers, json={
10
    "model": "openai/gpt-image-1",
11
    "prompt": "a detailed landscape painting",
12
    "stream": True
13
}, stream=True)
14
15
for line in response.iter_lines():
16
    if line:
17
        decoded = line.decode("utf-8")
18
        if decoded.startswith("data: ") and decoded != "data: [DONE]":
19
            import json
20
            event = json.loads(decoded[6:])
21
            print(f"Event: {event['type']}")

Request Parameters

Use the Image Models API to check which parameters each model and endpoint supports.