Image generation

Generate and edit images with one request. The endpoint has the shape of the OpenAI images API, so an unchanged OpenAI client works. Only a deployment that is registered to make images can win the job.

Quickstart

curl https://router.inference.ai.exchange/v1/images/generations \
  -H "Authorization: Bearer sk-liquid-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gemini-2.5-flash-image",
    "prompt": "a cat on a bicycle",
    "n": 2,
    "size": "1024x1024"
  }'

from openai import OpenAI

client = OpenAI(base_url="https://router.inference.ai.exchange/v1", api_key="sk-liquid-...")

result = client.images.generate(
    model="gemini-2.5-flash-image",
    prompt="a cat on a bicycle",
    n=2,
    size="1024x1024",
)

Each image comes back as b64_json or url. The exchange block of the answer holds the receipt. See Response.

Examples

Operators of the exchange made example images with each model. The page of a model in the console lists them. The app shows two here, each with its model and its prompt.

Find a model

A control works only when an offer for the model declares it. Read what a model supports before you send a control.

On the card of an image model:

• kind is image_generation and modality is image.
• image_sizes lists the pixel sizes that you can send as size. The tier and the shape come from these sizes. See Size, tier and shape.
• parameters lists each other control that at least one offer supports: output_format, quality, seed, background, output_compression and stream. A name that is not a key is not supported, so omit it. Modalities describes each descriptor.
• pricing gives the price of an image. If the price depends on a size or a quality, the line names it.

A preset of the image kind buys every listed model of its kind. If a request sets a control that no offer declared, the answer is 400 unsupported_parameter and param names the control or its feature, such as image.seed. The exchange holds nothing and sends nothing.

How it works

1. Send the request. The exchange picks the offers that can serve it.
2. The exchange fixes the price cap. The price is for one image, so the cap is exactly the charge.
3. The provider makes the images. The exchange dispatches the size that it resolved.
4. You get the answer, or events if you set stream. The charge is for the images that the provider returned.

Size, tier and shape

Send size when you know the pixel size. Send resolution or aspect_ratio when you do not. The exchange then picks a pixel size that an offer declared. It buys, prices and dispatches that size, as if you had sent it as size.

{ "model": "<model>", "prompt": "a cat on a bicycle", "resolution": "2K", "aspect_ratio": "16:9" }

• A tier is the pixel count of a square of that side. The tier of a size is the tier that is nearest to its area.
• A shape matches a size when the two ratios differ by 1% or less. aspect_ratio: "auto" asks for nothing.
• Without resolution, the exchange picks the size that is nearest to 1K.
• The size that the exchange picks sets the price. A model can charge more for a larger size.
• If no declared size has the tier and the shape, the answer is 400 unsupported_parameter. It lists the sizes that offers declare. A model with no declared size cannot be asked for a tier or a shape.
• If you send size as well and it has another tier or shape, the answer is 400 conflicting_parameters and names both fields.

Controls

seed, background, output_compression and stream are offer features: image.seed, image.background, image.output_compression and image.stream. An offer wins a request that sets one only when it declared the feature. An offer that did not declare it cannot win, because it would ignore the control and still charge for the image.

background: "auto" and stream: false ask for nothing. Any offer can win them.

Seed

seed makes a picture repeatable on a best-effort basis. An upstream can change its model.

{ "model": "<model>", "prompt": "a cat on a bicycle", "seed": 42 }

Background

background is transparent, opaque or auto. transparent needs output_format png or webp, or no output_format. With jpeg the answer is 400 conflicting_parameters.

{ "model": "<model>", "prompt": "a logo", "output_format": "png", "background": "transparent" }

Compression

output_compression is a whole number from 0 to 100. It applies to jpeg and webp. With png the answer is 400 conflicting_parameters.

{ "model": "<model>", "prompt": "a cat", "output_format": "webp", "output_compression": 80 }

Quality

An offer can list the quality names that it takes. If the offers of a model list any, the card has a quality key in parameters, and an offer that omits your name cannot win. An offer that lists none states nothing, so it can win and its provider decides. A provider that does not take the name fails the job before it renders, so send quality only when the model lists it.

Reference images

Send images in input_references to start from a picture. See Reference inputs. POST /v1/images/edits is the same purchase for the OpenAI SDK. It needs at least one reference image, takes the files in image, and refuses a mask.

Stream

Send stream: true to get the answer as server-sent events. The content type is text/event-stream. The request must ask for one image: stream with n above 1 gets 400 conflicting_parameters.

curl -N https://router.inference.ai.exchange/v1/images/generations \
  -H "Authorization: Bearer sk-liquid-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "<model>", "prompt": "a cat on a bicycle", "stream": true}'

event: image_generation.partial_image
data: {"type":"image_generation.partial_image","partial_image_index":0,"b64_json":"iVBOR…","media_type":"image/png"}

event: image_generation.completed
data: {"type":"image_generation.completed","b64_json":"iVBOR…","media_type":"image/png","exchange":{"...":"..."}}

• The exchange sends the events when the job ends, because the charge is known only then. It does not send the first draft early.
• A draft is not an image that you pay for. The charge counts the final image.
• If the winning offer does not stream, the answer is the normal JSON body.

Response

{
  "created": 1760000000,
  "data": [{ "b64_json": "iVBOR…", "media_type": "image/png" }],
  "exchange": { "...": "..." }
}

• Each image has b64_json or url, as the upstream of the provider returned it. media_type states the MIME type. revised_prompt appears when the upstream rewrote your prompt.
• The exchange does not download or host your images. A url is the link of the provider, and it can expire.
• The exchange block is the receipt. It reports images, so you can compare the images that you paid for with the images that you got. See Receipts.
• The answer and each event also have mime_type, with the same value as media_type, for clients that read the older name.

Billing

The price is for one image, so the cap that the exchange fixes is exactly the charge. The price of the size and the quality that the request names sets the charge. An image offer priced in tokens is held to the charge of one image at its output token bound.

exchange.limits.price.unit_usd sets the highest price for one image. See Purchasing rules and Modalities.

Images in a chat answer

Some chat models draw in their answer. Send modalities with image to POST /v1/chat/completions.

curl https://router.inference.ai.exchange/v1/chat/completions \
  -H "Authorization: Bearer sk-liquid-..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "<a model that draws in chat>",
    "modalities": ["image", "text"],
    "messages": [{ "role": "user", "content": "a cat on a bicycle" }]
  }'

Each image is in choices[0].message.images. The url of an image is a data: URL when the provider returned bytes. It is a link when the provider returned a link. The exchange does not change the form.

Only an offer that declared image output (output.image) can win the job. If no offer did, the exchange refuses the request with unsupported_parameter before the auction. It does not send you a text answer.

Image config

Send image_config to ask for a size. It needs image in modalities.

{
  "model": "<a model that draws in chat>",
  "modalities": ["image", "text"],
  "image_config": { "resolution": "2K", "aspect_ratio": "16:9" },
  "messages": [{ "role": "user", "content": "a cat on a bicycle" }]
}

• All values are strings. Send resolution or image_size, not both with different values.
• Any other key gets 400 invalid_request, and the error names the key, such as image_config.seed.
• An offer wins only when it declared a pixel size that has the size, the tier and the shape. An offer that declared output.image and no size cannot win a request with one of them.

Cost and limits in a chat answer

• An image costs output tokens. The charge is the output tokens that the provider reports, at the rate of the offer.
• If you send no max_tokens, the exchange allows 8,192 output tokens. Your price cap still limits the charge.
• If you set max_tokens below the size of one image, the model can stop before it draws. You pay for the tokens that it used.
• Send stream as false. A request with stream: true and image in modalities gets 400.
• /v1/messages and /v1/responses do not return images.
• If you hang up before the answer arrives, the job does not settle, and you are not charged.

Request parameters

A request that sends size, output_format or quality goes only to offers that serve that value, so it does not fail after the choice. If you omit size, the provider uses its default, and every offer for the model can answer.

Errors

See Errors for each code and exclusion reason.

Next steps

• Reference inputs: start from images, audio or video.
• Video generation: the same job for video.
• Modalities: the map of all modalities.