Images

Use POST /v1/images/generations with a JSON body:

{"model":"MODEL_ID_FROM_CATALOG","prompt":"A blue ceramic cup on a white table","n":1}

POST /v1/images/edits accepts multipart form data, including model, prompt fields and image upload(s). Let your HTTP library generate the multipart boundary. Preserve the same files, fields and idempotency key for a retry.

Supported sizes, output formats, image counts, masks and quality settings depend on the selected model. Respect catalog constraints. Results retain the provider's compatible response format, such as image URLs or base64 data; persist needed media in your application before provider URLs expire.

Read request_constraints.allowed_values from /v1/models for quality, background and output formats. The playground shows these choices as shape buttons and option groups for the selected provider route. Attach reference images with the file button or drag-and-drop in the composer; preview and remove each reference before running. Attaching images to a direct OpenAI route automatically selects edits. Exported code includes the same inline image data or multipart file fields as the request. Transparency is advertised only when background includes transparent; request PNG or WebP to preserve the alpha channel. JPEG cannot contain transparency. output_compression is an integer from 0 to 100 and applies only to JPEG or WebP.

For the reviewed GPT Image 2.5 generation routes:

{"model":"openai/gpt-image-2.5-sunburst","prompt":"A product cutout of a blue ceramic cup","n":1,"size":"1536x864","quality":"high","background":"transparent","output_format":"webp","output_compression":90}

The request_constraints.image_size object describes custom output bounds. Both edges must be multiples of 16 and no greater than 3840 pixels; total pixels must be between 655,360 and 8,294,400; the maximum aspect ratio comes from the selected route's maxAspectRatio. The direct GPT Image 2/2.5 defaults include operator-tested 864x3072 (9:32) and its landscape counterpart, while retaining the same pixel and edge bounds. OpenAI's published reference still specifies 3:1; the extended ratio is an operator-tested Cloud allowance and is not inferred for OpenRouter or other unreviewed routes. The gateway rejects invalid dimensions rather than silently changing the requested aspect ratio. Use size: "auto" to let the provider choose. Resolutions above 2560×1440 are experimental according to the provider guide.

Resolution and quality are independent. Input image resolution is not the output resolution. A generation-only route with text_input_only: true cannot accept reference images or edits. The reviewed GPT Image 2.5 routes accept multipart edits with up to 16 PNG, JPEG or WebP images, under 19 MiB total including a mask. Upload references as image or image[] and an optional mask as mask. Masks must match the first image's format and dimensions and have an alpha channel; the provider validates image content. JSON references to provider file IDs are not enabled on these routes. The playground includes a mask upload when the route advertises mask support. Google image requests can use native generationConfig.imageConfig in tasks or the reviewed OpenAI image style. Native Google references use contents[].parts[].inlineData with mimeType and base64 data. Reviewed Nano Banana 2/2.1 routes accept up to 14 PNG/JPEG/WebP references with 8 MiB total. Other Google image routes retain their own catalog count limits; these are Cloud admission limits, not the provider’s unrestricted maximum. Multipart Cloud edits translate to those native inline parts.

Image streaming and partial image output are not enabled on the default routes. Those outputs can add usage charges and need a reviewed streaming settlement adapter. The direct Images API and Responses image tool have different cache accounting; never assume their usage or cost is interchangeable.

Image pricing can use counts, quality/size variants, input/output image tokens or provider-reported cost. Do not estimate the final invoice from text token usage. The full meter set must be reviewed before a route is enabled.

JSON generation can also run as a durable task. Multipart task uploads are not supported; use the direct edit endpoint. The playground limits upload totals to 19 MiB to leave room under the gateway's 20 MiB body limit.

Provider routes

OpenAI and Coconut Studio use the OpenAI image transport. OpenRouter generation requests are translated from Cloud /v1/images/generations to its dedicated /api/v1/images endpoint. Cloud multipart edits with reference images translate to OpenRouter JSON input_references; native OpenRouter references accept inline data URLs. Remote reference URLs are rejected on these reviewed routes to avoid unbounded remote inputs. Translated masks are not supported. Each provider route has its own capability and billing review; sharing a canonical model does not share a price card.

Reviewed OpenRouter image routes include GPT Image 2.5 Sunburst/Flare, GPT Image 2, GPT Image 1/Mini and the GPT-5 image variants returned by the catalog. They support one output image, up to sixteen references within 8 MiB, and model-specific aspect ratios, quality and backgrounds. GPT Image 2.5 routes advertise transparency; GPT Image 2 does not advertise transparency on OpenRouter. Custom dimensions and streaming remain unavailable on these OpenRouter routes. Cloud settles from the exact provider usage.cost receipt, then applies the configured markup. A missing cost receipt retains the billing hold for reconciliation. See the OpenRouter Image API.

Coconut Studio is registered at https://p.coconutstudio.io/v1, using AI_PROVIDER_KEY_COCONUTSTUDIO. The Feeef operator confirmed a supplier cost of $0.05 per returned image on 2026-10-13, for edits and generation. Customer billing retains the reviewed OpenAI token tariff plus the configured Cloud markup (10% by default). Receipts expose provider_cost_usd separately from retail_basis_usd; the markup applies to the latter. This policy can charge less than supplier cost for small outputs; no hidden minimum is added. Both tariffs are frozen per request. Existing settled receipts retain their frozen price snapshots. A live test found that coconutstudio/gpt-image-2 accepted 864x3072 but returned 768x2048, and accepted 1024x1024 but returned 2048x2048. Its card now permits only size: "auto"; it makes no exact-dimension promise. Other route capabilities remain independently reviewed. Feeef's older $0.04/image catalog value is not automatically treated as a current supplier tariff. OpenAI uses AI_PROVIDER_KEY_OPENAI; OpenRouter uses AI_PROVIDER_KEY_OPENROUTER. Secrets stay on the gateway server.

Meta Model API is registered at https://api.meta.ai/v1, using AI_PROVIDER_KEY_META. The reviewed meta/muse-image-1.0 route supports one output image and up to ten PNG, JPEG or WebP references within 19 MiB; single edits upload as image, multi-image compositions as image[0] … image[N]. Muse Image always returns opaque images, so quality, background and compression options are not advertised on this route; size is an aspect-ratio hint and output_format accepts PNG, WebP or JPEG. Settlement is a flat $0.01 per returned image. See the Meta image generation guide.

Nano Banana 2 (gemini-3.1-flash-image) and Nano Banana 2.1 also advertise 1:4, 4:1, 1:8 and 8:1 in their native Google constraints. Supported resolution tiers remain route-specific. Native Nano Banana 2/2.1 and Pro image requests advertise a maximum output budget of 32,768 tokens; allow enough budget for the image and thinking, because a smaller limit can end with MAX_TOKENS and bill usage without producing an image. Read the route’s current maximum before constructing the request. See Google image generation.

Accepted parameters and actual output geometry are separate checks. A production Nano Banana 2.1 1:8 / 1K request returned a 352x2928 JPEG on 2026-10-13, while Google’s published table lists 384x3072. The option remains a documented supported request; that run did not certify exact output dimensions. Inspect the returned image when exact geometry matters. Recovering that published result keeps its original billing identity. See the provider dimensions table.