# GPT Image 2.6 Flare · Token — /images/generations

GPT Image 2.6 Flare, billed by tokens: the same model as `gpt-image-2.6-flare`, billed on the token usage OpenAI reports, at 72% of the official rates. Quality `xhigh` and `max` are available and `moderation: low` takes effect; 1K / 2K / 4K, 15 ratios, the original image as generated, nothing charged on failure. GIF output is not available yet.

**Endpoint:** `POST https://kovapi.com/v1/images/generations`

## Quick start

Three steps: submit a job, poll it, take the image link. Replace YOUR_API_KEY with your key and the commands below run as they are.

**Step 1 · Submit (returns a job id at once, HTTP 202)**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "A minimalist product shot of a white ceramic mug on a pale background, soft side light", "size": "16:9", "resolution": "2K"}'
```

Response (HTTP 202)

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "queued",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare-token"
}
```

**Step 2 · Poll every 2–3 seconds until `status` is `succeeded` or `failed`**

```
curl https://kovapi.com/v1/images/jobs/img_7f3c9a1e2b4d6f8a0c1e3b5d \
  -H "Authorization: Bearer YOUR_API_KEY"
```

Response when it succeeds

```
{
  "id": "img_7f3c9a1e2b4d6f8a0c1e3b5d",
  "object": "image.generation.job",
  "status": "succeeded",
  "created": 1791281400,
  "model": "gpt-image-2.6-flare-token",
  "data": [
    {"url": "https://img.kovapi.com/i/2be8cd16d37f3a4b9c0e1f2a3b4c5d6e.png"}
  ],
  "usage": {"images": 1, "resolution": "2K", "model": "gpt-image-2.6-flare-token"}
}
```

**Step 3 · `data[0].url` is the image (PNG). It is kept for 15 days; download it to your own storage to keep it longer.**

**Complete example (Python: submit, wait, save to disk)**

```
import time
import requests

BASE = "https://kovapi.com/v1"
HEADERS = {"Authorization": "Bearer YOUR_API_KEY"}

# 1. submit
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.6-flare-token",
    "prompt": "A minimalist product shot of a white ceramic mug on a pale background, soft side light",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. poll every 3 seconds until it finishes
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. download the image
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.6-flare-token.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## Authentication
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Request parameters

The JSON body of `POST /v1/images/generations`:

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| model | string | Yes | The model id: `gpt-image-2.6-flare-token`. |
| prompt | string | Yes | What to draw. For image-to-image, say what to change. |
| size | string | No | Ratio, one of the 15 in the table, e.g. `16:9`; or a pixel size, or `auto` (with references, follow the first reference's ratio). Without it the image is 1:1. |
| resolution | string | No | Tier: `1K` (default), `2K` or `4K`. |
| quality | string | No | Quality: `low`, `medium` (default), `high`, `xhigh`, `max` or `auto` (the model decides). Higher quality uses more tokens: at the same size about 0.57 / 1 / 1.21 / 2.1 / 4.8 times medium. |
| image / images | string / array | No | Reference images; sending one makes it image-to-image: `image` for one, `images` for several (up to 16). Public image links, data: URIs or base64. |
| n | integer | No | Number of images. Best left out: for several images submit several jobs at once. With `n`, n images are held up front and the images actually delivered are billed. |
| callback_url | string | No | Where to push the result when the job ends; see Webhooks below. |
| complexity | string | No | Planning depth: `low`, `medium` or `high`. It has no effect on the token-billed version yet (sending it is not an error) and does not change the price. |
| moderation | string | No | Moderation strictness: `auto` (default) or `low` (less strict, still within OpenAI's content policy). |
| output_compression | integer | No | Compression, a whole number 0-100, for `jpeg` / `webp` output only; lower means a smaller file. |
| mask_url | string | No | Mask for a regional edit: a PNG the same size as the first reference, transparent where the change goes. Needs a reference; cannot be combined with `markup_url`. The model follows the mask as guidance, not as a hard boundary. |
| markup_url | string | No | Markup layer: a transparent PNG with circles or marks where the change goes, laid over the first reference; say in the prompt what to do, e.g. "make the vase in the red circle blue and remove the circle". Needs a reference; cannot be combined with `mask_url`; up to 16.77 megapixels. |

`background` may be `transparent` (pair it with PNG or WebP output); `output_format` is `png` (default), `jpeg` or `webp`. `n` must be 1. A parameter not listed here returns 400 `unsupported_image_parameter` at submit and nothing is charged; the result comes back as `url`, and `usage` carries this job's tokens and charge.

## Billed by tokens

At submit, an upper bound is held from the size, quality and number of references; after the image is made the job settles on the usage OpenAI reports, and the rest of the hold is returned at once; a failure is refunded in full. Prices per 1M tokens:

| Item | Our price | OpenAI list price |
| --- | --- | --- |
| Image output | $21.6 | $30 |
| Image input (references) | $5.76 | $8 |
| Text input | $3.6 | $5 |

**Measured output tokens and cost (input not included)**

| size | quality | output tokens | USD |
| --- | --- | --- | --- |
| 1024x1024 | low | 824 | $0.018 |
| 1024x1024 | medium | 1,449 | $0.031 |
| 1024x1024 | high | 1,758 | $0.038 |
| 1024x1024 | xhigh | 3,122 | $0.067 |
| 1024x1024 | max | 7,024 | $0.152 |
| 2048x2048 | medium | 2,944 | $0.064 |
| 2048x2048 | max | 14,272 | $0.308 |
| 3840x2160 | medium | 2,855 | $0.062 |
| 3840x2160 | max | 13,342 | $0.288 |
| 3840x1280 | medium | 1,096 | $0.024 |

For the same size and quality the output tokens are the same every time, whatever the prompt; each reference adds about 700-1,600 image input tokens.

## Aspect ratio, resolution and output size

Put the ratio in `size` and the tier in `resolution`. You get the original image as generated, neither cropped nor resized, at the sizes below: both sides are multiples of 16, and 4K stays within 3840 px a side and about 8.3 megapixels.

| Aspect ratio | 1K | 2K | 4K |
| --- | --- | --- | --- |
| 1:1 | 1024x1024 | 2048x2048 | 2880x2880 |
| 3:4 | 768x1024 | 1536x2048 | 2480x3312 |
| 4:3 | 1024x768 | 2048x1536 | 3312x2480 |
| 2:3 | 672x1024 | 1360x2048 | 2336x3520 |
| 3:2 | 1024x672 | 2048x1360 | 3520x2336 |
| 9:16 | 608x1088 | 1152x2048 | 2160x3840 |
| 16:9 | 1088x608 | 2048x1152 | 3840x2160 |
| 4:5 | 816x1024 | 1632x2048 | 2576x3216 |
| 5:4 | 1024x816 | 2048x1632 | 3216x2576 |
| 1:2 | 576x1152 | 1024x2048 | 1920x3840 |
| 2:1 | 1152x576 | 2048x1024 | 3840x1920 |
| 9:21 | 544x1264 | 880x2048 | 1648x3840 |
| 21:9 | 1264x544 | 2048x880 | 3840x1648 |
| 1:3 | 480x1440 | 672x2016 | 1280x3840 |
| 3:1 | 1440x480 | 2016x672 | 3840x1280 |

- The 15 ratios in the table are supported; any other ratio returns 400 at submit and nothing is charged. With `size` set to `auto` and a reference image, the picture follows the ratio closest to the first reference; without one it is 1:1. A few long, narrow ratios at 1K are below the model's minimum pixel count and render at the enlarged sizes in the table (16:9 is 1088×608).

- `size` may also be a pixel size (e.g. `1536x1024`) in one of the 15 ratios: width and height are rounded down to multiples of 16, scaled down when above the tier's limit and scaled up to the model's minimum (about 655,000 pixels) when too small. The tier comes from `resolution`; without it, from the long side: up to 1536 is 1K, up to 2048 is 2K, larger is 4K. Long-side ranges: 1K 512-1536, 2K 2016-2304, 4K 2049-4096; outside them the request returns 400 at submit and nothing is charged.

## Quality and native resolution

- Without `quality` the image renders at medium. Quality changes only the tokens and the price, never the size; with `auto` the model decides, the hold assumes `max`, and the job settles on the real usage.

- If `quality` holds `1K`, `2K` or `4K` and `resolution` is not given, it is read as the resolution tier (size and price follow that tier).

- At busy times jobs wait in the queue instead of failing at once; if no image comes after a long wait (about 15 minutes) the job fails and is refunded in full, and you can resubmit it as is.

## Image-to-image and reference images

- Send `image` (one) or `images` (several, up to 16; any beyond that are not used) for image-to-image, and say in the prompt what to change. `POST /v1/images/edits` takes the same parameters.

- Both endpoints take a JSON body only, not a multipart file upload, so the OpenAI SDK's `images.edit()` cannot be used as is: pass links or base64 as in the example below.

- Each reference may be a public image link (http / https), a data: URI or plain base64, up to 16 MB, in PNG, JPEG or WebP; a reference in any other format fails the job and the hold is refunded in full.

- A URL has to download the image itself: not a web page, and not behind a login or hotlink protection. A reference we cannot read is refused at submit with a 400 that says which one and why; no job is created and nothing is charged.

- The output ratio comes from `size`, not from the reference. To keep the original ratio, set `size` to it.

- We host the references for you and keep them for 7 days.

**Image-to-image with two references**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "Keep the people, change the background to a beach at night with warm string lights", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## Job status and fields

`GET /v1/images/jobs/{id}` reports these statuses; every field is described in [Async jobs](https://docs.kovapi.com/en/guide/async-jobs#fields). Poll every 2–3 seconds, or use a webhook.

| Status | Meaning |
| --- | --- |
| queued | Waiting in line. Carries `queue_position` (jobs ahead of yours) and `eta_seconds` (expected wait). |
| processing | Rendering. |
| succeeded | Done. The result is in `data[0].url`, the billing detail in `usage`. |
| failed | Failed. The reason is in `error`; the credits held for the job are refunded in full. |

One account runs up to 50 jobs at a time; further jobs wait in submission order, and a job that has not started after 15 minutes fails and is refunded in full. Job records are kept for 3 days and image links for 15 days.

## How long it takes

Usually 20–60 seconds from submit to result; 4K, edits with several references and busy periods take longer, and an occasional job takes a minute or two.

## Errors and refunds

An error at submit comes back at once as HTTP 4xx / 5xx: no job is created and nothing is charged. A failure after the job was accepted is reported by the job endpoint, and the hold is refunded in full. Every code is listed under [Error codes](https://docs.kovapi.com/en/guide/errors).

### Errors at submit

| HTTP | code | Cause | What to do |
| --- | --- | --- | --- |
| 400 | missing_prompt | `/v1/images/generations` has no `prompt`. | Add a `prompt`. |
| 400 | invalid_request | A reference image cannot be read (dead link, not an image, over 16MB...; `message` says which one and why), `/v1/images/edits` has no reference image, the body is not a JSON object, or `n` is not an integer. | Fix what `message` says and submit again. |
| 400 | model_not_found | The model id is misspelled, `model` is missing, or the model cannot be used on this endpoint (a chat model on the image endpoint, for example). | Use a model id from `GET /v1/models` or the [API reference](https://docs.kovapi.com/en/api). |
| 401 | invalid_api_key | The key does not exist, was deleted or is disabled, or the account is disabled. | Check the key on the API Keys page of the console. |
| 402 | insufficient_quota | Not enough balance to hold this request. The gateway holds the highest possible cost of the request first, so a burst of concurrent calls can trigger it too. | After a burst, wait a few seconds and retry; otherwise top up. |
| 429 | rate_limit_exceeded | Over the requests-per-minute limit set on this key (counted over the last 60 seconds). No `Retry-After` header. | Wait a few seconds and retry, or raise the key's limit in the console. |
| 503 | model_maintenance | The model is under maintenance and takes no requests; no other model answers in its place meanwhile. | Retry when maintenance ends; see [Status](https://kovapi.com/en/status). |
| 503 | service_unavailable | A temporary failure on our side, such as storing a reference file; `/v1/responses` also answers 503, with `Retry-After`, when it cannot take requests for a moment. | Retry shortly. |

### Failed jobs (`status` `failed`)

| code | When you see it | What to do |
| --- | --- | --- |
| moderation_blocked | Image: the model provider's safety system refused the prompt or a reference image (the code may also be `content_policy_violation`). | Rewrite the prompt or replace the reference; resubmitting it unchanged is usually refused again. |
| upstream_error | Any other failure: the automatic retries did not help, the job waited 15 minutes without starting, the upstream refused without a reason, and so on; `message` says which. | Submitting again usually works. |

## Webhooks instead of polling

Add `callback_url` when you submit and the moment the job ends, success or failure, the gateway pushes exactly what the poll endpoint returns to that URL, signed and retried on failure. You can also set an account-wide address under Settings → Webhook in the console. [Webhook docs →](https://docs.kovapi.com/en/webhooks)

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-flare-token", "prompt": "A minimalist product shot of a white ceramic mug on a pale background, soft side light", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```