Images
Every image model behind one request shape. Per-model credits, prompt
limits, input-image caps and qualities are listed under Image models on the
overview, and the aspect ratios in GET /models/.
Generate an image
Submits an image job and charges it. Supplying input media turns the request into an edit; the models differ in how many inputs they accept (see Image models on the overview).
Pass upload ids in uploads. A positional image1 is read here only as a
file part, so an upload id sent in it is ignored. Send
multipart/form-data instead of JSON to attach files directly as
image1…imageN.
Headers
Idempotency-KeyMakes this submission safe to retry. A replay within 15 minutes returns
the original body with status 200 and is not charged again; a replay while
the first request is still in flight returns 409 request_in_progress.
The key is fingerprinted with the request's prompt (its dialogue, for
speech), so reusing a key with a different prompt starts a new
generation. A client_request_id body field works identically.
Generate an image › Request Body
modelAccepted as mode too; if both are sent, mode wins. Exceeding
the model's input-image cap fails with too_many_images.
promptWhat to render, or how to edit the inputs. Over the model's
max_prompt_chars fails with prompt_too_long.
image_urlsPublicly reachable https:// image URLs. Hoosha media links are rejected with invalid_image_url; send those files through uploads. Repeat the field in multipart.
uploadsUpload ids from POST /uploads/. Each id is single-use and expires
about 20 minutes after the upload. /images/ reads upload ids only
from this field; an id sent as image1 is ignored.
aspect_ratioDefaults to auto on chatgpt-image-2.0, the
chatgpt-image-2.5-* models and nano-banana-2-1, and to 1:1
on chatgpt-image-1.5 and grok-imagine-2. Those models check
the value: an unsupported ratio fails with
invalid_aspect_ratio. The other models replace a ratio they
cannot render instead of rejecting it: hoosha-v1 renders auto,
nano-banana-2-pro and seedream4 render 1:1, and
flux_kontext renders 16:9, which includes the 4:3 default.
Stay within each model's aspect_ratios in GET /models/.
qualityQuality-tiered models only (nano-banana-2-1,
nano-banana-2-pro, chatgpt-image-2.0 and the
chatgpt-image-2.5-* models) — it selects the price tier, and
defaults to 1K on nano-banana-2-1. Ignored by every other
model. Also accepted as resolution; quality wins if both are
sent. Anything else fails with invalid_quality.
levelchatgpt-image-2.5-* models only; ignored by the other models.
low and medium cost the table price. high, xhigh and
max need a fixed aspect_ratio and 2K or 4K, hold the
credits in the levels table and settle to the actual cost once
the image is delivered. Anything else fails with
invalid_level.
backgroundchatgpt-image-2.5-* models only, at every level; ignored by the
other models. Anything else fails with invalid_background.
output_formatnano-banana-2-pro only; ignored by the other models. Anything
else fails with invalid_output_format.
Generate an image › Responses
An Idempotency-Key replay within 15 minutes. The body is byte-identical
to the original 202 and nothing was charged again.
idPoll this with GET /generations/{id}/.
typeMedia type of the job.
modelThe model as you requested it.
statusAlways processing — nothing is rendered yet.
credits_chargedAlready debited. This is the final price, except for seedance25 edit/extend jobs where it is a hold that is partially refunded after delivery.
created_at