---
title: "Generate an image"
method: POST
path: "/images"
tags: ["Images"]
---

# Generate an image

`POST /images`

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

## Request body

- ImageGenerationRequest — Image generation request input
  - `aspect_ratio` '1:1' | '1:2' | '1:4' | '1:8' | '2:1' | '2:3' | '3:2' | '3:4' | '4:1' | '4:3' | '4:5' | '5:4' | '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).
  - `input_references` ContentPartImage[] — Reference images to guide image-to-image generation, as base64 data URLs or HTTP(S) URLs.
    - `image_url` object, required
      - `url` string, required
    - `type` 'image_url', required
  - `model` string, required — The image generation model to use
  - `n` integer — Number of images to generate (1-10). Providers that only support single-image generation reject n > 1.
  - `output_compression` integer — 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`.
  - `prompt` string, required — Text description of the desired image
  - `provider` object — Provider-specific passthrough configuration
    - `options` object — Provider-specific options keyed by provider slug. Only options for the matched provider are forwarded; the rest are ignored. Unrecognized keys are silently dropped.
      - `01ai` object
      - `ai21` object
      - `aion-labs` object
      - `akashml` object
      - `alibaba` object
      - `amazon-bedrock` object
      - `amazon-nova` object
      - `ambient` object
      - `anthropic` object
      - `anyscale` object
      - `arcee-ai` object
      - `atlas-cloud` object
      - `atoma` object
      - `avian` object
      - `azure` object
      - `baidu` object
      - `baseten` object
      - `black-forest-labs` object
      - `byteplus` object
      - `centml` object
      - `cerebras` object
      - `chutes` object
      - `cirrascale` object
      - `clarifai` object
      - `cloudflare` object
      - `cohere` object
      - `crofai` object
      - `crucible` object
      - `crusoe` object
      - `darkbloom` object
      - `decart` object
      - `deepinfra` object
      - `deepseek` object
      - `dekallm` object
      - `digitalocean` object
      - `enfer` object
      - `fake-provider` object
      - `featherless` object
      - `fireworks` object
      - `friendli` object
      - `gmicloud` object
      - `google-ai-studio` object
      - `google-vertex` object
      - `gopomelo` object
      - `groq` object
      - `heygen` object
      - `huggingface` object
      - `hyperbolic` object
      - `hyperbolic-quantized` object
      - `inception` object
      - `inceptron` object
      - `inferact-vllm` object
      - `inference-net` object
      - `infermatic` object
      - `inflection` object
      - `inocloud` object
      - `io-net` object
      - `ionstream` object
      - `klusterai` object
      - `lambda` object
      - `lepton` object
      - `liquid` object
      - `lynn` object
      - `lynn-private` object
      - `mancer` object
      - `mancer-old` object
      - `mara` object
      - `meta` object
      - `minimax` object
      - `mistral` object
      - `modal` object
      - `modelrun` object
      - `modular` object
      - `moonshotai` object
      - `morph` object
      - `ncompass` object
      - `nebius` object
      - `nex-agi` object
      - `nextbit` object
      - `nineteen` object
      - `novita` object
      - `nvidia` object
      - `octoai` object
      - `open-inference` object
      - `openai` object
      - `parasail` object
      - `perceptron` object
      - `perplexity` object
      - `phala` object
      - `poolside` object
      - `quiver` object
      - `recraft` object
      - `recursal` object
      - `reflection` object
      - `reka` object
      - `relace` object
      - `replicate` object
      - `sakana-ai` object
      - `sambanova` object
      - `sambanova-cloaked` object
      - `seed` object
      - `sf-compute` object
      - `siliconflow` object
      - `sourceful` object
      - `stealth` object
      - `stepfun` object
      - `streamlake` object
      - `switchpoint` object
      - `targon` object
      - `tenstorrent` object
      - `together` object
      - `together-lite` object
      - `ubicloud` object
      - `upstage` object
      - `venice` object
      - `wafer` object
      - `wandb` object
      - `xai` object
      - `xiaomi` object
      - `z-ai` object
  - `quality` 'auto' | 'low' | 'medium' | 'high' — Rendering quality. Providers without a quality knob ignore this.
  - `resolution` '512' | '1K' | '2K' | '4K' — Normalized resolution tier of the generated image. Concrete pixel dimensions are derived per-provider.
  - `seed` integer — 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` string — 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.
  - `stream` boolean — 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.

## Response `200`

Image generation response

- ImageGenerationResponse — Image generation response
  - `created` integer, required — Unix timestamp (seconds) when the image was generated
  - `data` object[], required — Generated images
    - `b64_json` string, required — Base64-encoded image bytes
    - `media_type` string — Media type (MIME type) of the image. Omitted when the output is a standard raster format (PNG). Present for non-raster outputs such as SVG (`image/svg+xml`).
  - `usage` ImageGenerationUsage — Token and cost usage for the image generation request, when available
    - `completion_tokens` integer, required — The tokens generated
    - `completion_tokens_details` object, nullable
      - `audio_tokens` integer, nullable — Tokens generated by the model for audio output.
      - `image_tokens` integer, nullable — Tokens generated by the model for image output.
      - `reasoning_tokens` integer, nullable — Tokens generated by the model for reasoning.
    - `cost` number, double, nullable — Cost of the completion
    - `cost_details` CostDetails, nullable — Breakdown of upstream inference costs
      - `upstream_inference_completions_cost` number, double, required
      - `upstream_inference_cost` number, double, nullable
      - `upstream_inference_prompt_cost` number, double, required
    - `is_byok` boolean — Whether a request was made using a Bring Your Own Key configuration
    - `iterations` AnthropicUsageIteration[], nullable
      - union
        - AnthropicCompactionUsageIteration
          - `cache_creation` AnthropicIterationCacheCreation, nullable
            - `ephemeral_1h_input_tokens` integer
            - `ephemeral_5m_input_tokens` integer
          - `cache_creation_input_tokens` integer
          - `cache_read_input_tokens` integer
          - `input_tokens` integer
          - `output_tokens` integer
          - `type` 'compaction', required
        - AnthropicMessageUsageIteration
          - `cache_creation` AnthropicIterationCacheCreation, nullable
            - `ephemeral_1h_input_tokens` integer
            - `ephemeral_5m_input_tokens` integer
          - `cache_creation_input_tokens` integer
          - `cache_read_input_tokens` integer
          - `input_tokens` integer
          - `output_tokens` integer
          - `model` string
          - `type` 'message', required
        - AnthropicAdvisorMessageUsageIteration
          - `cache_creation` AnthropicIterationCacheCreation, nullable
            - `ephemeral_1h_input_tokens` integer
            - `ephemeral_5m_input_tokens` integer
          - `cache_creation_input_tokens` integer
          - `cache_read_input_tokens` integer
          - `input_tokens` integer
          - `output_tokens` integer
          - `model` string, required
          - `type` 'advisor_message', required
        - AnthropicUnknownUsageIteration
          - `cache_creation` AnthropicIterationCacheCreation, nullable
            - `ephemeral_1h_input_tokens` integer
            - `ephemeral_5m_input_tokens` integer
          - `cache_creation_input_tokens` integer
          - `cache_read_input_tokens` integer
          - `input_tokens` integer
          - `output_tokens` integer
          - `type` string, required
    - `prompt_tokens` integer, required — Including images, input audio, and tools if any
    - `prompt_tokens_details` object, nullable — Breakdown of tokens used in the prompt.
      - `audio_tokens` integer, nullable — Tokens used for input audio.
      - `cache_write_tokens` integer, nullable — Tokens written to cache. Only returned for models with explicit caching and cache write pricing.
      - `cached_tokens` integer, nullable — Tokens cached by the endpoint.
      - `file_tokens` integer, nullable — Tokens used for input files/documents.
      - `video_tokens` integer, nullable — Tokens used for input video.
    - `server_tool_use` object, nullable — Usage for server-side tool execution (e.g., web search)
      - `tool_calls_executed` integer, nullable — Number of OpenRouter server tool calls that executed and produced a result.
      - `tool_calls_requested` integer, nullable — Total number of OpenRouter server-orchestrated tool calls the model requested, across all tool types. Provider-native tools (e.g. native web search) are not counted here.
      - `web_search_requests` integer, nullable — Number of web searches performed by server-side tools. For server-orchestrated tool calls a web search is also counted in tool_calls_requested; provider-native web search may report web_search_requests only. Do not sum the two.
    - `service_tier` string, nullable — The service tier used by the upstream provider for this request
    - `speed` 'fast' | 'standard' | 'null', nullable
    - `total_tokens` integer, required — Sum of the above two fields

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed input
- `401` — Unauthorized - Authentication required or invalid credentials
- `402` — Payment Required - Insufficient credits or quota to complete request
- `403` — Forbidden - Authentication successful but insufficient permissions
- `404` — Not Found - Resource does not exist
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - Unexpected server error
- `502` — Bad Gateway - Provider/upstream API failure
- `524` — Infrastructure Timeout - Provider request timed out at edge network
- `529` — Provider Overloaded - Provider is temporarily overloaded

## Changes

- **2026-06-26** `7fd444475582` — 2 info
  - added the new optional request property `provider/options/allOf[#/components/schemas/ProviderOptions]/quiver`
  - added the new `svg` enum value to the request property `output_format`
- **2026-06-26** `4524b440d463` — 2 info
  - added the optional property `data/anyOf[#/components/schemas/ImageGenCompletedEvent]/media_type` to the response with the `200` status (media type: text/event-stream)
  - added the optional property `data/items/media_type` to the response with the `200` status (media type: application/json)
- **2026-06-24** `1de249ed4255` — 1 info
  - added the new optional request property `provider/options/allOf[#/components/schemas/ProviderOptions]/heygen`
- **2026-06-24** `8758fa27fe84` — 1 info
  - added the new optional request property `provider/options/allOf[#/components/schemas/ProviderOptions]/inferact-vllm`
- **2026-06-24** `bae0fe0fb859` — 1 info
  - added the new optional request property `provider/options/allOf[#/components/schemas/ProviderOptions]/sakana-ai`

[Full history](https://skmtc.dev/openrouterteam/apis/openrouter-api/changes/images/post.md)

---

[API](https://skmtc.dev/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.dev/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/revisions/654dd48df2fd/schema)