Skip to main content

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 is https://api.nunchux.com. There is no poll route. The images are in the response.

Request

Send your API key in the X-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.
string
required
The model ID: gpt-image-2.6-sunburst or gpt-image-2.6-flare.
string
required
What to generate, or how to change the input images. Up to 32,000 characters.
integer
default:"1"
How many images to return, 1 to 10. Each image is billed.
string
default:"auto"
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.
string
default:"auto"
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.
string
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.
string
default:"png"
The file format of the returned images: png, jpeg or webp. svg and gif are not offered.
integer
The compression level for jpeg and webp output, 0 to 100.
string
default:"auto"
transparent, opaque or auto. A transparent background needs png or webp output.
string
default:"auto"
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.
object[]
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.
object
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.
object
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.
The route forwards other fields of OpenAI’s Images API to OpenAI unchanged. 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 an x-correlation-id header. Quote it when you contact support.
object[]
One item per image, in order.
object
The tokens that OpenAI counted for the request. Your charge is computed from these counts.
integer
When the images were created, as a Unix timestamp in seconds.
string
The size that was rendered, such as 1024x1024. With size set to auto, this is the size that OpenAI picked.
string
The quality that was rendered.
string
The file format of the images.
string
The background that was rendered: transparent or opaque.
Response

Example

Generate an image and save it to a file.
To edit, send the body below to 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.
  1. When Nunchux accepts the request, it holds the most the request can cost. The hold grows with n, size, quality and the number of input images. size set to auto is held as 1536x1024, and quality set to auto as high.
  2. When OpenAI answers, Nunchux settles the charge to the usage block in the response. The charge can only go down from the hold, never up.
If the response comes back without a 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 low quality on Flare. A low image at 1024x1024 returns in a few seconds and costs the fewest output tokens.
  • Set quality yourself. auto renders and bills at high.
  • Ask for several images in one request rather than several requests. n up to 10 shares one prompt and one call.
  • Use jpeg or webp with output_compression when 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 high image 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.