> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nunchux.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Authenticate every request with your API key in the `X-API-Key` header or `Authorization: Bearer`. Keys start with `sk-nunchux-`.
> Image generation is synchronous: the image is in the response.
> Video generation is asynchronous: submit the job, poll its task until it reaches a terminal status, then download the output promptly, because output URLs expire.

# GPT Image

> OpenAI's GPT Image 2.6 Sunburst and Flare for text-to-image and image editing, in one synchronous call billed in tokens.

# 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.

> [!NOTE]
>
> This page covers OpenAI's own models, called on the `/v2/openai` routes with OpenAI's request body. The [OpenAI compatibility](https://docs.nunchux.ai/nunchux-optimized/openai-compatibility.md) page is a different thing: it lets the OpenAI SDK call Nunchux Optimized models on `/v1/images`.

> [!NOTE]
>
> 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

| Model | Model ID | Tasks | Quality | Images per request |
| - | - | - | - | - |
| GPT Image 2.6 Sunburst | `gpt-image-2.6-sunburst` | Generate, edit | `low`, `medium`, `high`, `auto` | 1 to 10 |
| GPT Image 2.6 Flare | `gpt-image-2.6-flare` | Generate, edit | `low`, `medium`, `high`, `auto` | 1 to 10 |

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`.

| Step | Method | Path |
| - | - | - |
| Generate | `POST` | `/v2/openai/images/generations` |
| Edit | `POST` | `/v2/openai/images/edits` |

There is no poll route. The images are in the response.

## Request

Send your API key in the `X-API-Key` header. See [Authentication](https://docs.nunchux.ai/authentication.md). 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.

**model** `string` *required*

The model ID: `gpt-image-2.6-sunburst` or `gpt-image-2.6-flare`.

**prompt** `string` *required*

What to generate, or how to change the input images. Up to 32,000 characters.

**n** `integer` (default: 1)

How many images to return, 1 to 10. Each image is billed.

**size** `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.

**quality** `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.

**complexity** `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.

**output\_format** `string` (default: png)

The file format of the returned images: `png`, `jpeg` or `webp`. `svg` and `gif` are not offered.

**output\_compression** `integer`

The compression level for `jpeg` and `webp` output, 0 to 100.

**background** `string` (default: auto)

`transparent`, `opaque` or `auto`. A transparent background needs `png` or `webp` output.

**moderation** `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.

**images** `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.

**mask** `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.

**markup** `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.

**data** `object[]`

One item per image, in order.

**properties**

**b64\_json** `string`

The image, base64-encoded, in the requested `output_format`. GPT Image always returns base64. There is no image URL.

**generation\_id** `string`

OpenAI's ID for this image.

**usage** `object`

The tokens that OpenAI counted for the request. Your charge is computed from these counts.

**properties**

**input\_tokens** `integer`

All input tokens. `input_tokens_details` splits them into `text_tokens` (the prompt) and `image_tokens` (the input images, the mask and the markup).

**output\_tokens** `integer`

All output tokens. `output_tokens_details.image_tokens` counts the generated images.

**total\_tokens** `integer`

Input and output tokens together.

**created** `integer`

When the images were created, as a Unix timestamp in seconds.

**size** `string`

The size that was rendered, such as `1024x1024`. With `size` set to `auto`, this is the size that OpenAI picked.

**quality** `string`

The quality that was rendered.

**output\_format** `string`

The file format of the images.

**background** `string`

The background that was rendered: `transparent` or `opaque`.

```json Response theme={"system"}
{
  "created": 1795132002,
  "background": "opaque",
  "output_format": "png",
  "quality": "low",
  "size": "1024x1024",
  "data": [
    { "generation_id": "...", "b64_json": "iVBORw0KGgo..." }
  ],
  "usage": {
    "input_tokens": 28,
    "input_tokens_details": { "image_tokens": 0, "text_tokens": 28 },
    "output_tokens": 1643,
    "output_tokens_details": { "image_tokens": 1643, "text_tokens": 0 },
    "total_tokens": 1671
  }
}
```

## Example

Generate an image and save it to a file.

```bash cURL theme={"system"}
curl https://api.nunchux.com/v2/openai/images/generations \
  -H "X-API-Key: $NUNCHUX_API_KEY" \
  -H "Content-Type: application/json" \
  -H "User-Agent: my-app/1.0" \
  -d '{
    "model": "gpt-image-2.6-flare",
    "prompt": "a red paper lantern on a wooden table, warm evening light",
    "size": "1024x1024",
    "quality": "low"
  }' \
  | python3 -c 'import base64, json, sys; open("lantern.png", "wb").write(base64.b64decode(json.load(sys.stdin)["data"][0]["b64_json"]))'
```

```python Python theme={"system"}
import base64
import os

import requests

response = requests.post(
    "https://api.nunchux.com/v2/openai/images/generations",
    headers={
        "X-API-Key": os.environ["NUNCHUX_API_KEY"],
        "Content-Type": "application/json",
        "User-Agent": "my-app/1.0",
    },
    json={
        "model": "gpt-image-2.6-flare",
        "prompt": "a red paper lantern on a wooden table, warm evening light",
        "size": "1024x1024",
        "quality": "low",
    },
    timeout=120,
)
response.raise_for_status()
body = response.json()

for i, image in enumerate(body["data"]):
    with open(f"lantern-{i}.png", "wb") as f:
        f.write(base64.b64decode(image["b64_json"]))

print(body["usage"])
```

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.

```json Edit theme={"system"}
{
  "model": "gpt-image-2.6-sunburst",
  "prompt": "make the lantern blue and add a second one beside it",
  "images": [
    { "image_url": "https://example.com/lantern.png" }
  ],
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "webp",
  "output_compression": 80
}
```

## 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](https://nunchux.ai/pricing) 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](https://docs.nunchux.ai/credits-pricing.md).

## 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](https://docs.nunchux.ai/errors.md). These request shapes are rejected with 400 before any charge:

| Code | Cause |
| - | - |
| `unknown_model` | The model is not one of the IDs above. |
| `invalid_request` | A field is out of range: `n` outside 1 to 10, a size outside the limits above, `n` times the image size above 24,000,000 pixels, `quality` set to `xhigh` or `max`, `moderation` set to `low` without approval, `images` on a generation, or an edit without `images`. |
| `stream_not_supported` | `stream` is `true`. |
| `partial_images_not_supported` | `partial_images` is above 0. |
| `output_format_not_supported` | `output_format` is `svg` or `gif`. |
| `invalid_image` | An input image is not an `https` URL or a base64 `data:image/...` URI. |
| `file_id_not_supported` | An input image names a `file_id` instead of an `image_url`. |

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](https://docs.nunchux.ai/rate-limits.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.