Create image

Generate images over the OpenAI Images-compatible endpoint. The official SDKs work unchanged.

Compared with the text endpoints, two behaviors matter in practice:

  • Artifacts are stored in object storage and returned in amux.images. Stored artifacts are cleaned up on a schedule, so download anything you need to keep; afterwards the address returns 404;
  • We reserve an estimated amount when the request is accepted, then settle against actual usage and release the difference. If your available balance cannot cover that reserve, the request returns 402 immediately.

Streaming (stream: true) returns SSE with the same events OpenAI uses: zero or more image_generation.partial_image frames (low-resolution previews), then one image_generation.completed carrying the final image and usage. partial_images sets how many previews you want (0-3, default 0 — completed only). If rendering finishes quickly, you may receive fewer previews than requested.

Two limits:

  • One image per request (n must be 1). Nothing in the stream events says which image a frame belongs to, so several cannot be told apart;
  • Only providers that support image streaming take part in routing. When none does, you get an explicit error instead of a silent fallback to non-streaming.
post/v1/images/generations

Request

  • Base URL: https://gateway.amux.ai
  • URL: https://gateway.amux.ai/v1/images/generations
  • Auth: HTTP bearer

Request body

modelstring required

Model ID, optionally suffixed with :provider to pin a provider.

promptstring required

The prompt.

ninteger

How many images (1-10, default 1). Billed per image, and the reserve scales with it. Must be 1 when streaming.

sizestring

An exact pixel size, or auto (the default).

⚠️ The accepted set differs per model:

  • gpt-image-1.5: a closed set — only 1024x1024 / 1536x1024 / 1024x1536 / auto. Any other pixel string is rejected upstream, including ones that satisfy the four rules below;
  • gpt-image-2, gpt-image-2.5-flare, gpt-image-2.5-sunburst: those three plus 2048x2048, 2048x1152, 3840x2160, 2160x3840, the 4:3 and 3:4 tiers 1024x768 / 768x1024 / 2048x1536 / 1536x2048 / 3264x2448 / 2448x3264, and any pixel string meeting all four rules — both edges a multiple of 16, long edge at most 3840, aspect ratio at most 3:1, total pixels between 655,360 and 8,294,400. A 3840-pixel long edge leaves at most 2160 on the other side, so the widest tier is 16:9 or wider; the largest 4:3 that fits the pixel ceiling is 3264x2448.

Sending a tier the chosen model does not take is rejected upstream. See that model's own reference for its exact set.

⚠️ Size drives the image token count, and therefore the price.

auto is exempt — read size in the response to see what you got.

This and the Google-style "aspect ratio + resolution tier" are parallel; when the upstream speaks only the other one we convert and say so in amux.notes.

aspect_ratiostring

An alternative spelling of size (the Google-ecosystem form), used together with image_size. Send one form or the other; if both are given, size wins. The accepted set differs per model — see the model pages. ⚠️ On the OpenAI models, prefer size. Those upstreams take exact pixel sizes only, so a ratio is folded into one of them; the fold is lossy, and a ratio with no exact match is approximated or dropped, with a note in amux.notes. The xAI image models are the other way round: they take aspect_ratio natively and do not accept size at all.

image_sizestring

Resolution tier, used with aspect_ratio. The accepted set differs per model.

quality'low' | 'medium' | 'high' | 'xhigh' | 'max' | 'auto'

⚠️ The accepted set differs per model: xhigh and max are accepted only by gpt-image-2.5-flare and gpt-image-2.5-sunburst; sending either to gpt-image-2 or gpt-image-1.5 is rejected upstream. The xAI image models take low / medium / auto only. Render quality. It drives the image token count and therefore the price — the tiers can differ by an order of magnitude.

background'transparent' | 'opaque' | 'auto'

A transparent background needs png or webp; jpeg has no alpha channel. Transparency on gpt-image-2 is still a preview capability.

output_format'png' | 'jpeg' | 'webp'

Output format, png by default.

output_compressioninteger

Compression level; only meaningful for jpeg / webp.

moderation'auto' | 'low'

Moderation strictness. Generation endpoint only.

userstring

End-user identifier for abuse monitoring. Omit the key entirely if you do not need it.

streamboolean

Return SSE. Requires n of 1 and at least one provider that streams.

partial_imagesinteger

How many low-resolution previews to send while streaming. 0 (the default) means the completed event only. You may get fewer than you asked for — a fast render goes straight to the completed event.

Example request

{
  "model": "openai/gpt-image-2",
  "prompt": "A red fox sitting in snow, photorealistic",
  "size": "1024x1024"
}

Response

Success. data and usage match OpenAI; amux is our extension.

createdinteger

Unix timestamp (seconds) of when generation finished.

sizestring

The size the upstream actually used. When the request said size: 'auto', this is the only place that answers "how big is it".

qualitystring

The quality tier actually used.

backgroundstring

The background handling actually used.

output_formatstring

The artifact's actual format.

Example response

{
  "created": 1786000000
}

Changes

No recorded changes to this operation across all 1 revision of this API.