GPT Image
GPT Image is OpenAI’s image model family. It generates images from a text prompt, and it edits images that you send with the prompt. The call is synchronous: one POST returns the finished images in the response body, so there is nothing to poll. The routes mirror OpenAI’s Images API, so the request and response shapes are the provider’s.This page covers OpenAI’s own models, called on the
/v2/openai routes with OpenAI’s request body. The OpenAI compatibility page is a different thing: it lets the OpenAI SDK call Nunchux Optimized models on /v1/images.Best for
- Several images at once. One request returns up to 10 images.
- Edits with many inputs. One edit takes up to 16 input images, with an optional mask.
Models
Both models take the same fields and are billed at the same rates per token. Flare is the faster of the two. Draft on Flare, then compare Sunburst on the prompts that matter.
Endpoints
The base URL ishttps://api.nunchux.com.
There is no poll route. The images are in the response.
Request
Send your API key in theX-API-Key header. See Authentication. Set Content-Type: application/json. The examples also send a User-Agent header that names your application.
Both routes take JSON only. An edit sends its input images as URLs or base64 data URIs in the body, not as a multipart upload. A multipart request returns 415.
auto, or a size written as WIDTHxHEIGHT, such as 1024x1024, 1536x1024 or 1024x1536. Both edges must be multiples of 16 and at most 3840 pixels. The long edge can be at most three times the short edge. The image must have between 655,360 and 8,294,400 pixels in total. A larger image costs more output tokens. auto lets OpenAI pick the size.low, medium, high or auto. auto renders at high. Higher quality costs more output tokens and takes longer. OpenAI’s xhigh and max are not offered, because they can take longer than the synchronous call waits.How much effort the model spends planning the image before it renders:
low, medium or high. It is separate from quality. Leave it out to use OpenAI’s default.The file format of the returned images:
png, jpeg or webp. svg and gif are not offered.The strictness of OpenAI’s content filter. Send
auto or leave it out. low is available only to accounts that Nunchux has approved to turn moderation down. From any other account, low returns 400.Edit only, and required there. The input images, 1 to 16. Each item is
{ "image_url": "..." }, where the value is a public https URL or a base64 data:image/... URI. OpenAI’s file_id form is not accepted. A generation body that sends images returns 400.Edit only. A mask over the first input image, as
{ "image_url": "..." }. The transparent areas of the mask mark where the model may change the image.Edit only. A PNG with transparent areas, laid over the first input image to show the model where and what to change, as
{ "image_url": "..." }. It must have the same dimensions as that image. Send mask or markup, not both.stream and partial_images are not offered, because the route returns one complete response.
Response
A 200 response has OpenAI’s image body. The response also carries anx-correlation-id header. Quote it when you contact support.
The size that was rendered, such as
1024x1024. With size set to auto, this is the size that OpenAI picked.Response
Example
Generate an image and save it to a file.POST /v2/openai/images/edits instead. Replace the image_url with a public URL of your own image. The response has the same shape.
Edit
Billing
OpenAI bills in tokens, and so does Nunchux. A request is billed on three counts, each at its own rate per million tokens: text input tokens, image input tokens and image output tokens. The pricing page lists the rates. The charge comes in two steps within the one request.- When Nunchux accepts the request, it holds the most the request can cost. The hold grows with
n,size,qualityand the number of input images.sizeset toautois held as1536x1024, andqualityset toautoashigh. - When OpenAI answers, Nunchux settles the charge to the
usageblock in the response. The charge can only go down from the hold, never up.
usage block, the hold is charged in full. A request that returns no images, because it was refused, throttled or timed out, is refunded in full. Each request appears in GET /v1/usage with its credits_used. See Credits & pricing.
Tips
- Draft at
lowquality on Flare. Alowimage at1024x1024returns in a few seconds and costs the fewest output tokens. - Set
qualityyourself.autorenders and bills athigh. - Ask for several images in one request rather than several requests.
nup to 10 shares one prompt and one call. - Use
jpegorwebpwithoutput_compressionwhen file size matters. The base64 body of a large PNG can run to tens of megabytes. - Set your client timeout to at least 120 seconds. A
highimage at a large size can take over a minute.
Errors and limits
A failed request returns an HTTP error status. See Error codes. These request shapes are rejected with 400 before any charge:
When OpenAI’s content filter blocks a prompt or an input image, the request returns 400 with the code
moderation_blocked. It is refunded.
When OpenAI throttles the request, it returns 429 with the code vendor_throttled. The request is refunded. When the response carries a Retry-After header, wait that many seconds before you retry. Otherwise retry with backoff.
The call waits about 100 seconds for OpenAI. A render that takes longer returns 504 with the code engine_timeout. It is refunded, and the images are lost. Lower quality, size or n before you try again.
A 502, 503 or 504 means that the request did not reach OpenAI or its answer did not come back. It is refunded. Retry with backoff.
Requests count toward the rate limits of your plan. See Rate limits.