GPT Image 2.5 API

Authentication

All requests carry the API key in the header:

Authorization: Bearer YOUR_API_KEY

Pricing (per image, by resolution × quality)

quality accepts low, medium, high, xhigh and max, and **each tier is priced differently** — you pay for the detail you ask for: a layout check at 1K low is $0.008, and you only reach for max when the image is going to print. gpt-image-2.5-flare is the default tier (about half the latency of GPT Image 2 — social, e-commerce, high volume) and both renders and bills at **medium** unless you pass quality; gpt-image-2.5-sunburst targets premium commercial visuals and defaults to **high**, so pass quality explicitly if you do not want to be billed at the high rate. At 1K and 2K the two models cost the same at every quality tier, so at those sizes you are choosing speed, not price. 4K is priced per model: sunburst is $0.020 / $0.085 / $0.16 / $0.28 / $0.47 (low to max), while flare stays at $0.020 / $0.045 / $0.08 / $0.17 / $0.30. The tier is decided by the total pixel count of the image you actually get back — 1.7MP or less bills as 1K, 1.7-4.6MP as 2K, above 4.6MP as 4K — not by its longest edge and not by the parameter you sent. A 2K image at 2720x1536 is 4.18MP, so it bills as 2K even though its long edge exceeds 2048; with size auto or omitted the output decides, so pass an explicit size if you need a fixed tier. Reference images and transparent background cost nothing extra; failed requests are not charged. gpt-image-2.5 is an alias of flare.

Sizes & billing tiers

4K is delivered exactly as requested: 3840x2160 / 2160x3840 (8.29MP). 2K at 1:1 is 2048x2048; for other ratios we request 2720x1536 / 1536x2720 (4.18MP), and the image comes back either at that size or at the same aspect ratio with a 2048px long edge (about 2048x1152 at 16:9, roughly 2.4MP) — the size the official OpenAI documentation uses as its “2K” example. Both fall inside the 2K pixel band, keep your aspect ratio and are billed as 2K. 1K at 1:1 is exact as well (1024² measured as returned); 16:9 / 9:16 requests at 1K (1360x768 / 768x1360) come back as either 1360x768 or 1672x941 — two outputs from the same channel, same aspect ratio, both billed as 1K. Alternatively omit size and pass aspect_ratio + resolution (1K/2K/4K) and the server derives the size.

Option 1: OpenAI SDK / Codex / Cursor (sync)

Passing an OpenAI-style WxH size triggers sync mode: the response carries the image inline (b64_json + url), matching the official images.generate() / images.edit() contract. Waiting and timeout rules are the same as GPT Image 2 All (280s cap, keep-alive after 95s; a failure after the 95s mark is carried in the body as an error field).

# Text-to-image — OpenAI Images API shape, SYNC response (no task polling)
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "a ceramic teapot, product shot, studio light",
    "size": "1024x1024",
    "background": "transparent",
    "output_format": "png",
    "n": 1
  }'
# → { "created": ..., "data": [{ "b64_json": "...", "url": "https://r2.apimodels.app/..." }] }

# Image edit — multipart, OpenAI images.edit() shape. No mask field: name the
# object to change in the prompt and say the rest stays (see Notes below).
curl -X POST https://api.apimodels.app/v1/images/edits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "model=gpt-image-2.5-sunburst" \
  -F "image=@product.png" \
  -F "prompt=change the red label to a green label, keep everything else exactly the same" \
  -F "size=2048x2048"

Option 2: native async (taskId + poll / callback)

Without a WxH size (or when you need callback_url) the request follows the platform async contract: create returns a taskId; poll until completed, or receive a webhook callback.

# Native async contract — pass aspect_ratio + resolution tier instead of size.
curl -X POST https://api.apimodels.app/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "a lighthouse on a cliff at dusk",
    "aspect_ratio": "9:16",
    "resolution": "2K",
    "callback_url": "https://your-domain.com/webhook"
  }'
# → { "code": 200, "data": { "taskId": "..." } }

curl "https://api.apimodels.app/v1/images/generations?task_id=TASK_ID" \
  -H "Authorization: Bearer YOUR_API_KEY"

Parameters

Examples by tier

One image from each of seven price cells, generated through the apimodels.app API on 2026-09-19: the verbatim prompt, requested size, delivered size and wall time are the real values from that call; **prices are labelled at the current rate card after the 2026-09-22 cut**, not what was billed then. Click an image for the full-size original. Note that the Sunburst 4K image predates the 2026-09-22 channel change — the channel serving it then snapped sizes to its own grid, which is why its delivered size is smaller than the request; the same request now delivers 3840x2160, and that sample is due to be re-shot. The two 2K images came back at 2048x1136 / 1136x2048, a same-ratio size with a 2048px long edge — 2K today still returns either that kind of size or the requested 2720x1536 / 1536x2720, and both bill as 2K.

Notes

• No mask support: a request to /v1/images/edits carrying mask / mask_url / mask_base64 returns 400. A mask is only worth taking if it is a hard boundary, and none of the upstream channels we tested treats it as one — they accept it, return 200 and repaint the protected region anyway (measured at 1K low: a reference image with a red left half and a white right half, a mask protecting the right half, prompt "paint the background deep blue"; both halves came back with the identical average RGB, and the other mask convention, greyscale white means editable, gave the same result). Rather than accept a parameter we would silently ignore, we reject it. For local edits, name the object in the prompt and say the rest stays: "turn the red circle blue, keep everything else" changed only the circle in our tests. Migrating from the official OpenAI API: drop the mask field, everything else is unchanged.
• Measured latency (production medians over the last 7 days, external traffic, 2026-09-19): about 45s at 1K (p90 ~65s), about 25s flare / 40s sunburst at 2K, about 35s sunburst / 50s flare at 4K; reference-image edits 15-50s. For sync calls set client timeouts to ≥180s.
• Content credentials (C2PA): to get OpenAI's C2PA signature you must send output_format: "png" — that path returns the upstream PNG untouched and the signature survives intact (verified 2026-09-22 across tiers and both models). Otherwise opaque images are re-encoded to JPEG q95 and the signature is lost in that step, so the delivered file carries no metadata at all. The trade-off is size: the same 2K image is about 5.9MB as PNG versus about 1.1MB as JPEG.
• Upload size: requests through apimodels.app are capped at ~4.5MB per request body (413 beyond that). For large images or many references, switch base_url to https://api.apimodels.app/v1 — same API, same key, 100MB per request.
• Failed generations are not charged. Result files are auto-deleted after 30 days — download or re-host promptly.

Try it in the Playground