Images

Generate an image

Changed on

Generates an image from a text prompt via the image generation router

post/images

Request

  • Base URL: https://openrouter.ai/api/v1
  • URL: https://openrouter.ai/api/v1/images
  • Auth: HTTP bearer

Request body

aspect_ratio'1:1' | '1:2' | '1:4' | '1:8' | '2:1' | '2:3' | '2.35:1' | '3:2' | '3:4' | '4:1' | '4:3' | '4:5' | '5:2' | '5:4' | '5:7' | '7:5' | '8:1' | '9:16' | '16:9' | '9:19.5' | '19.5:9' | '9:20' | '20:9' | '9:21' | '21:9' | 'auto'

Normalized aspect ratio of the generated image. Providers clamp to their supported subset.

background'auto' | 'transparent' | 'opaque'

Background treatment. transparent requires an output_format that supports alpha (png or webp).

modelstring required

The image generation model to use

ninteger

Upper bound on the number of images to generate (1-10). Providers may return fewer images, and providers that only support single-image generation reject n > 1.

output_compressioninteger

Compression level (0-100) for webp/jpeg output. Ignored for png and by providers without a compression knob.

output_format'png' | 'jpeg' | 'webp' | 'svg'

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.

promptstring required

Text description of the desired image

quality'auto' | 'low' | 'medium' | 'high' | 'xhigh' | 'max'

Rendering quality. Providers without a quality knob ignore this.

resolution'512' | '768' | '1K' | '1.5K' | '2K' | '4K'

Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider.

seedinteger

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.

session_idstring

A unique identifier for grouping related requests (e.g., a conversation or agent workflow). Used for observability grouping in Broadcast and private logging; never sent to the provider. If provided in both the request body and the x-session-id header, the body value takes precedence. Maximum of 256 characters.

sizestring

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.

streamboolean

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.

userstring

A stable identifier for your end-users. Used to help detect and prevent abuse. Never sent to providers verbatim: for providers whose data policy requires user IDs, it is folded into a hashed, per-account upstream user identifier.

Example request

{
  "model": "bytedance-seed/seedream-4.5",
  "prompt": "a red panda astronaut floating in space, studio lighting"
}

Response

Image generation response

createdinteger required

Unix timestamp (seconds) when the image was generated

Example response

{
  "created": 1748372400,
  "data": [
    {
      "b64_json": "<base64-encoded-image>"
    }
  ],
  "usage": {
    "completion_tokens": 4175,
    "cost": 0.04,
    "prompt_tokens": 0,
    "total_tokens": 4175
  }
}

Changes

  • 96aa3bc7df90Revision changes
    • info

      added the new 1.5K enum value to the request property

  • 68a12e66c7faRevision changes
    • info

      added the new optional request property //////

    • info

      added the new ElevenLabs enum value to the request property //////

    • info

      added the new ElevenLabs enum value to the request property //////

    • info

      added the new ElevenLabs enum value to the request property //////