Summary: OpenRouter launched the Unified Image API on June 23 to expose 30-plus models through one request shape and queryable schemas for capabilities, parameters, endpoints, and pricing. Models differ in resolutions, aspect ratios, batch limits, reference inputs, and streaming, and billing remains split among image, megapixel, and token units, so callers should normalize estimates and reconcile with usage cost. Existing image models still work through completions and responses, but new image models will arrive only in the dedicated API.
For anyone wiring up image generation, the request formats are the shallow problem. The deep one is that capabilities truly diverge: which resolutions and aspect ratios a model accepts, how many reference images it takes, how many images it returns per call, whether it can stream — every model answers these differently. Normalizing the field names while ignoring those gaps just swaps one flavor of 400 error for a different one. The Unified Image API that OpenRouter launched on June 23 takes the other route: a single request shape, plus queryable schema covering each model’s capabilities, parameters, and pricing. According to the announcement, this dedicated API reaches 30+ models from Google, OpenAI, Black Forest Labs, Recraft, ByteDance, Sourceful, Microsoft, and xAI, and the roster keeps growing.
Check what a model can do before you call
The division of labor is easy to state: /api/v1/images/models tells you what each model supports; POST /api/v1/images does the generating (Bearer API key authentication). The models endpoint returns typed capability descriptors for every model — the resolutions and aspect ratios it takes, its largest batch, reference-image ceilings, seed availability, streaming support — structured fields all the way down, no marketing copy.
Those gaps run wider than most people guess. Per the announcement: Seedream 4.5 offers 18 aspect ratios to Gemini 3.1 Flash Image’s 14, overlapping sets that don’t match. Batch size reaches 10 images per call on some models and stops at 1 on the rest. Input-reference ceilings differ as well — the post’s prose has it that some models take 16 references and others 4. One detail deserves a pause: in that same post, the Seedream 4.5 descriptor example sets the input_references range at 0 to 14, so prose and example are out of step — cite the section you’re quoting. Don’t guess; read the descriptor:
{
"resolution": { "type": "enum", "values": ["1K", "2K", "4K"] },
"n": { "type": "range", "min": 1, "max": 10 },
"input_references": { "type": "range", "min": 0, "max": 14 },
"seed": { "type": "boolean" },
"supports_streaming": false
}The block above is an abridged slice of the announcement’s descriptor for bytedance-seed/seedream-4.5 — id, the supported_parameters wrapper, and aspect_ratio were dropped here; every value that remains matches the source. With it, your code — or your coding agent — validates parameters locally before the request leaves, rather than baking each provider’s limits into its own adapter and learning them through 400 errors. Hardcoded limit tables go stale quickly as the model list expands; a descriptor compresses adapter logic into one query and a cache.
One request shape, three ways to bill
On the request side, resolution, aspect_ratio, quality, output format, background transparency, input references, and streaming are normalized so they behave the same across providers. Provider-specific parameters — Black Forest Labs’ steps and guidance, for example — ride in through provider.options, keyed by the provider slug. Every endpoint also publishes an allowed_passthrough_parameters list that spells out exactly which passthrough keys it accepts, so what gets through is a lookup rather than an experiment.
Multiple providers can serve one model. /api/v1/images/models/{id}/endpoints reports the parameters each endpoint truly accepts, its streaming support, and granular pricing. Every endpoint response carries a pricing array; Seedream 4.5’s entry is {"billable": "output_image", "unit": "image", "cost_usd": 0.04} — what gets billed, in which unit, at what price, on one line, so a cost estimator consumes data instead of docs. Pricing is the most candid corner of this API, because the billing units themselves were never unified:
| Model (per announcement) | Billing unit | Price |
|---|---|---|
| Seedream 4.5 | per image | $0.04 |
| FLUX.2 Pro | per megapixel | $0.03, and resolution decides the bill |
| GPT-5.4 Image 2, Gemini 3.1 Flash Image | per token | charged by usage |
Each unit implies a different cost curve. Per-image billing ignores resolution and is the simplest to forecast. Per-megapixel billing grows in lockstep with resolution — only the unit price is published, so the 1K-to-4K multiplier is arithmetic you do yourself, not an official figure. Per-token billing follows what generation actually consumes, so advance planning means an estimate range. Routing on cost starts with converting the three units into comparable estimates; after that, every response’s usage object carries the exact USD cost, so reconciliation involves no guessing.
Streaming previews, and who should move
Streaming coverage is uneven as well. Per the announcement, OpenAI’s GPT Image family — GPT-5 Image, GPT-5 Image Mini, GPT-5.4 Image 2 — streams natively over SSE: set stream: true and partial previews of the image arrive as it renders. On longer renders, those previews replace a spinner-filled wait with progress you can see. For every other model, trust the supports_streaming field rather than assumptions.
Official migration guidance draws a single clear line: image models that already exist keep working through completions/responses, but new image models will land only in the dedicated Image API. OpenRouter further recommends that users of openai/gpt-5-image, gpt-5-image-mini, and gpt-5.4-image-2 switch to the dedicated image models — those versions generate images through an LLM, ship incomplete parameter sets, and can add extra inference cost. If your product still runs the old path, this launch is your cue to move — the price of staying on completions exceeds incomplete parameters: none of the image models coming later will ever show up there.
Unified plumbing, not unified output
Set expectations honestly: this API unifies integration work, not what the images look like. Feed one prompt to different models and you get different styles, and each handles reference images its own way. Keep evaluation sets of your own for the models that matter — composition, text rendering, character consistency, safety policy — the questions no API will answer for you.
Capability descriptors make switching models dependable; they don’t make models interchangeable parts. Choosing models and verifying quality stays on your plate. (The framing in this section is the author’s judgment, not the announcement’s.)
What builders should do now
Three actions to take today. One: at startup, call /api/v1/images/models, cache the capability schema, and validate locally — stop spending runtime calls on trial and error. Two: before routing on cost, normalize the billing units into comparable estimates, then reconcile against the usage cost in each response. Three: if images still come from chat completions, follow the official advice onto the dedicated image models — complete parameter sets, without the extra inference cost. Begin in the playground; the docs hold the details.