--- 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` ImageGenerationProviderPreferences — Provider routing preferences and provider-specific passthrough configuration. - `allow_fallbacks` boolean, nullable — Whether to allow backup providers to serve requests - true: (default) when the primary provider (or your custom providers in "order") is unavailable, use the next best provider. - false: use only the primary/custom provider, and return the upstream error if it's unavailable. - `ignore` union[], nullable — List of provider slugs to ignore. If provided, this list is merged with your account-wide ignored provider settings for this request. - union - 'Modal' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Claude Platform on AWS' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'CoreWeave' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Fish Audio' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Mara' | 'Mancer 2' | 'Meta' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'VoyageAI by MongoDB' | 'NCompass' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Sail Research' | 'Sakana AI' | 'SambaNova' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tencent' | 'Tenstorrent' | 'Thinking Machines' | 'Together' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Krea' | 'Runway' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider' - string - `only` union[], nullable — List of provider slugs to allow. If provided, this list is merged with your account-wide allowed provider settings for this request. - union - 'Modal' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Claude Platform on AWS' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'CoreWeave' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Fish Audio' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Mara' | 'Mancer 2' | 'Meta' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'VoyageAI by MongoDB' | 'NCompass' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Sail Research' | 'Sakana AI' | 'SambaNova' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tencent' | 'Tenstorrent' | 'Thinking Machines' | 'Together' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Krea' | 'Runway' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider' - string - `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 - `claude-on-aws` object - `cloudflare` object - `cohere` object - `coreweave` object - `crofai` object - `crucible` object - `crusoe` object - `darkbloom` object - `decart` object - `deepgram` object - `deepinfra` object - `deepseek` object - `dekallm` object - `digitalocean` object - `enfer` object - `fake-provider` object - `featherless` object - `fireworks` object - `fish-audio` 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 - `krea` 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 - `runway` object - `sail-research` object - `sakana` 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 - `tencent` object - `tenstorrent` object - `thinkingmachines` object - `together` object - `together-lite` object - `ubicloud` object - `upstage` object - `venice` object - `voyageai` object - `wafer` object - `wandb` object - `wandb-legacy` object - `xai` object - `xiaomi` object - `z-ai` object - `order` union[], nullable — An ordered list of provider slugs. The router will attempt to use the first provider in the subset of this list that supports your requested model, and fall back to the next if it is unavailable. If no providers are available, the request will fail with an error message. - union - 'Modal' | 'AkashML' | 'AI21' | 'AionLabs' | 'Alibaba' | 'Ambient' | 'Baidu' | 'Amazon Bedrock' | 'Amazon Nova' | 'Anthropic' | 'Arcee AI' | 'AtlasCloud' | 'Avian' | 'Azure' | 'BaseTen' | 'BytePlus' | 'Black Forest Labs' | 'Cerebras' | 'Chutes' | 'Cirrascale' | 'Claude Platform on AWS' | 'Clarifai' | 'Cloudflare' | 'Cohere' | 'CoreWeave' | 'Crucible' | 'Crusoe' | 'Darkbloom' | 'Decart' | 'Deepgram' | 'DeepInfra' | 'DeepSeek' | 'DekaLLM' | 'DigitalOcean' | 'Featherless' | 'Fireworks' | 'Fish Audio' | 'Friendli' | 'GMICloud' | 'Google' | 'Google AI Studio' | 'Groq' | 'HeyGen' | 'Inception' | 'Inceptron' | 'InferenceNet' | 'Ionstream' | 'Infermatic' | 'Io Net' | 'Inferact vLLM' | 'Inflection' | 'Liquid' | 'Mara' | 'Mancer 2' | 'Meta' | 'Minimax' | 'ModelRun' | 'Mistral' | 'Modular' | 'Moonshot AI' | 'Morph' | 'VoyageAI by MongoDB' | 'NCompass' | 'Nebius' | 'Nex AGI' | 'NextBit' | 'Novita' | 'Nvidia' | 'OpenAI' | 'OpenInference' | 'Parasail' | 'Poolside' | 'Perceptron' | 'Perplexity' | 'Phala' | 'Recraft' | 'Reka' | 'Relace' | 'Sail Research' | 'Sakana AI' | 'SambaNova' | 'Seed' | 'SiliconFlow' | 'Sourceful' | 'StepFun' | 'Stealth' | 'StreamLake' | 'Switchpoint' | 'Tencent' | 'Tenstorrent' | 'Thinking Machines' | 'Together' | 'Upstage' | 'Venice' | 'Wafer' | 'WandB' | 'Quiver' | 'Krea' | 'Runway' | 'Xiaomi' | 'xAI' | 'Z.AI' | 'FakeProvider' - string - `sort` union — The sorting strategy to use for this request, if "order" is not specified. When set, no load balancing is performed. - 'price' | 'throughput' | 'latency' | 'exacto' — The provider sorting strategy (price, throughput, latency) - ProviderSortConfig — The provider sorting strategy (price, throughput, latency) - `by` 'price' | 'throughput' | 'latency' | 'exacto' | 'null', nullable — The provider sorting strategy (price, throughput, latency) - `partition` 'model' | 'none' | 'null', nullable — Partitioning strategy for sorting: "model" (default) groups endpoints by model before sorting (fallback models remain fallbacks), "none" sorts all endpoints together regardless of model. - `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. 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. - `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, e.g. `image/png`, `image/jpeg`, `image/webp`, `image/svg+xml`. May be omitted if the format could not be determined. - `usage` ImageGenerationUsage — Token and cost usage for the image generation request, when available - `cache_creation` AnthropicCacheCreation, nullable - `ephemeral_1h_input_tokens` integer, required - `ephemeral_5m_input_tokens` integer, required - `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 - `413` — Payload Too Large - Request payload exceeds size limits - `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 --- [API](https://skmtc.net/openrouterteam/apis/openrouter-api.md) · [All operations](https://skmtc.net/openrouterteam/apis/openrouter-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/openrouterteam/openrouter-api/versions/9d1da2c7d2c3/schema)