Create image

Text-to-image with openai/gpt-image-2.5-sunburst, over the OpenAI-compatible endpoint. An official SDK works unchanged once its base_url points here.

Sunburst is the quality-optimised variant of the 2.5 pair, intended for work in which editing precision and fidelity take priority over turnaround. Where generation speed is the priority, use gpt-image-2.5-flare instead. The two accept an identical parameter set; they differ only in behaviour.

Authorization

header

AuthorizationstringRequired

Bearer <your Amux key> Your Amux API key.

Request

application/json

modelstringRequired

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

promptstringRequired

The prompt.

nintegerDefault 1

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). Common tiers:

1024x1024 (1:1), 1536x1024 / 1024x1536 (3:2 landscape /

portrait), 1024x768 / 768x1024 (4:3 landscape / portrait),

2048x2048 (2K square), 2048x1152 (16:9),

2048x1536 / 1536x2048 (2K 4:3), 3840x2160 / 2160x3840

(4K 16:9), 3264x2448 / 2448x3264 (4K 4:3).

Beyond those, any pixel string works with both edges a multiple

of 16, long edge at most 3840, aspect ratio at most 3:1, and total

pixels between 655,360 and 8,294,400. A 3840-pixel long edge leaves

at most 2160 on the other side, so that tier is 16:9 or wider; the

largest 4:3 within the pixel ceiling is 3264x2448.

⚠️ 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

1:1 / 4:3 / 3:4 / 3:2 / 2:3 / 16:9 / 9:16. An alternative spelling of size (the Google-ecosystem form); send one or the other. If both are given, size wins and we say so in amux.notes.

⚠️ Prefer size where you can. This upstream takes exact pixel sizes only, so a ratio is folded into one of them, together with image_size when given. The fold is lossy: a ratio with no exact match is approximated to the nearest available size, and if nothing is close enough the field is dropped — either way with a note in amux.notes. size states the result you want and is passed through unchanged.

image_sizestring

1K / 2K / 4K. Used together with aspect_ratio; same rules.

quality"low" | "medium" | "high" | "xhigh" | "max" | "auto"Default "auto"

Render quality. It drives the image token count and therefore the price — the tiers can differ by an order of magnitude. xhigh and max are new in 2.5 and sit above high: measured at 1024x704, the five tiers cost 120 / 262 / 1,078 / 1,916 / 4,310 image tokens. Sending xhigh or max to a 2.x model is rejected upstream.

background"transparent" | "opaque" | "auto"Default "auto"

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

output_format"png" | "jpeg" | "webp"Default "png"

Output format, png by default.

output_compressionintegerDefault 100

Compression level; only meaningful for jpeg / webp.

moderation"auto" | "low"Default "auto"

Moderation strictness. Generation endpoint only.

userstring

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

streambooleanDefault false

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

partial_imagesintegerDefault 0

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.

Response

200response

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

400response

Invalid request. Also covers "streaming asked for but no provider streams" and "streaming with n above 1" — both say what to change.

402response

Not enough available balance to cover this request's reserve.

Available = balance − expired lots − already reserved.

503response

No provider available. Two common causes: this model has no image provider

configured, or the size tier you asked for has no price on that provider —

metadata says which.

Quality tiers#

GPT-Image-2.5 accepts five tiers plus auto, adding xhigh and max above high. These are distinct tiers, not aliases: each produces a different image token count and a correspondingly different charge.

xhigh and max are specific to 2.5. Sending either to gpt-image-2 or gpt-image-1.5 is rejected upstream.

The per-tier figures were measured on flare. Sunburst bills the same: at max the two models returned identical image-token counts at 1024x704, 2048x2048 and 3840x2160. What differs is latency, not the bill.

When migrating from gpt-image-2, note that the tiers do not correspond one to one: at the same size, 2.5's high costs what 2.0's medium did, and 2.5's max costs what 2.0's high did. Copying a quality value across the two models changes both the output and the charge.

Official price reference#

The figures below are OpenAI's published list prices, provided as an order-of-magnitude reference when selecting parameters. They are not what we charge: requests through this gateway are billed below OpenAI list. For our actual unit prices see the model page; for the cost of a specific call, read usage in the response.

OpenAI's published token rates for this model are: text input $5/M, cached text input $1.25/M, image input $8/M, cached image input $2/M and image output $30/M. Image output dominates the total, so at list prices a single 1024x1024 image costs approximately:

Size affects the total as much as quality does. At max:

Note the final two rows: 4K costs slightly less than 2K square, because image tokens saturate near 14,000 rather than tracking pixel count.

Size and cost#

The common tiers:

Beyond those, any pixel string works if both edges are a multiple of 16, the long edge is at most 3840, the aspect ratio is at most 3:1, and the total pixel count is between 655,360 and 8,294,400.

A 3840-pixel long edge leaves at most 2160 on the other side, so that tier is available only at 16:9 or wider. The largest 4:3 within the pixel ceiling is 3264x2448.

Prefer size. aspect_ratio plus image_size is accepted as an alternative spelling, but this upstream takes exact pixel sizes only, so the pair is folded into one of the sizes above. The fold is lossy: a ratio outside this table is approximated to the nearest listed one, and if nothing is close enough the field is dropped — either way with a note in amux.notes. size states the result you want and is passed through unchanged.

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

Image tokens do not grow without bound: at max they saturate near 14,000, so 2048x2048 costs marginally more than 3840x2160. Select the size the output requires rather than the one assumed to be cheaper.

Latency#

At quality: max, a single 1024x704 image took approximately 106 seconds in our measurements. Allow for this: raise client and proxy timeouts, or use the task endpoint in place of the synchronous one.

Artifact retention#

amux.images carries directly usable addresses and data[].b64_json carries this call's image. Stored artifacts are removed after a retention period. Download anything that must be kept; once removed, the address returns 404.

Streaming#

stream: true returns SSE; partial_images (0-3) sets how many low-resolution previews are returned. The final image and usage arrive in the same completed event, and a fast render may finish before all requested previews are emitted.

n must be 1 when streaming. If no provider currently streams images, the request is rejected with an explanatory message; remove stream and the model remains available.

Errors#

The error shape matches OpenAI. See Errors and retries for the type values and their retry semantics.

curl https://gateway.amux.ai/v1/images/generations \
  -H "Authorization: Bearer $AMUX_API_KEY" \
  -d '{
    "model": "openai/gpt-image-2.5-sunburst",
    "prompt": "A red fox sitting in snow, photorealistic",
    "size": "1024x1024"
  }'

{
  "created": 1786000000,
  "size": "<string>",
  "quality": "<string>",
  "background": "<string>",
  "output_format": "<string>",
  "data": [
    {
      "b64_json": "<string>",
      "revised_prompt": "<string>"
    }
  ],
  "usage": {
    "input_tokens": 0,
    "output_tokens": 0,
    "total_tokens": 0
  },
  "amux": {
    "task_id": "<string>",
    "generation_id": "<string>",
    "provider": "<string>",
    "cost_nano": "<string>",
    "images": [
      {
        "index": 0,
        "url": "<string>"
      }
    ],
    "notes": [
      "<string>"
    ]
  }
}