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

GPT Image 2.6 Sunburst с оплатой по токенам: та же модель, что `gpt-image-2.6-sunburst`, оплата по использованию токенов, которое сообщает OpenAI, по 72% официальных тарифов. Доступно качество `xhigh` и `max`, `moderation: low` действует; 1K / 2K / 4K, 15 соотношений сторон, оригинал в том виде, как сгенерирован, при неудаче ничего не списывается. Вывод GIF пока недоступен. В часы нагрузки задания ждут в очереди.

**Эндпоинт:** `POST https://kovapi.com/v1/images/generations`

## Быстрый старт

Три шага: отправить задачу, опросить её и забрать ссылку на изображение. Замените YOUR_API_KEY своим ключом, и команды ниже заработают как есть.

**Шаг 1 · Отправка (сразу возвращает id задачи, 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-sunburst-token", "prompt": "Картина маслом: гавань в сумерках, заметные мазки, тёплая палитра", "size": "16:9", "resolution": "2K"}'
```

Ответ (HTTP 202)

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

**Шаг 2 · Опрашивайте каждые 2–3 секунды, пока `status` не станет `succeeded` или `failed`**

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

Ответ при успехе

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

**Шаг 3 · `data[0].url` — это изображение (PNG). Оно хранится 15 дней; чтобы пользоваться им дольше, скачайте его в своё хранилище.**

**Полный пример (Python: отправить, дождаться, сохранить на диск)**

```
import time
import requests

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

# 1. отправка
job = requests.post(f"{BASE}/images/generations", headers=HEADERS, json={
    "model": "gpt-image-2.6-sunburst-token",
    "prompt": "Картина маслом: гавань в сумерках, заметные мазки, тёплая палитра",
    "size": "16:9",
    "resolution": "2K",
}).json()
if "error" in job:
    raise SystemExit(job["error"]["message"])

# 2. опрос каждые 3 секунды до завершения
while job["status"] not in ("succeeded", "failed"):
    time.sleep(3)
    job = requests.get(f"{BASE}/images/jobs/{job['id']}", headers=HEADERS).json()

# 3. скачивание изображения
if job["status"] == "succeeded":
    url = job["data"][0]["url"]
    with open("gpt-image-2.6-sunburst-token.png", "wb") as f:
        f.write(requests.get(url).content)
    print("saved", url)
else:
    print("failed:", job["error"]["code"], job["error"]["message"])
```

## Аутентификация
```
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

## Параметры запроса

JSON-тело запроса `POST /v1/images/generations`:

| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| model | string | Да | ID модели: `gpt-image-2.6-sunburst-token`. |
| prompt | string | Да | Что нарисовать. Для изображения из изображения опишите, что нужно изменить. |
| size | string | Нет | Соотношение сторон, одно из 15 в таблице, например `16:9`; или размер в пикселях, или `auto` (с референсами — по соотношению первого). Без него изображение 1:1. |
| resolution | string | Нет | Уровень: `1K` (по умолчанию), `2K` или `4K`. |
| quality | string | Нет | Качество: `low`, `medium` (по умолчанию), `high`, `xhigh`, `max` или `auto` (решает модель). Чем выше качество, тем больше токенов: при том же размере примерно 0,57 / 1 / 1,21 / 2,1 / 4,8 от medium. |
| image / images | string / array | Нет | Референсы; с ними включается режим «изображение в изображение»: `image` — одно, `images` — несколько (до 16). Публичные ссылки, data: URI или base64. |
| n | integer | Нет | Количество изображений. Лучше не передавать: если нужно несколько изображений, отправьте сразу несколько задач. При указании `n` заранее резервируется стоимость n изображений, а оплачиваются фактически выданные. |
| callback_url | string | Нет | Куда отправить результат, когда задача завершится; подробнее — в разделе о вебхуках ниже. |
| complexity | string | Нет | Глубина продумывания: `low`, `medium` или `high`. В версии с оплатой по токенам пока не действует (передавать можно, ошибки не будет) и не меняет цену. |
| moderation | string | Нет | Строгость модерации: `auto` (по умолчанию) или `low` (мягче, в рамках политики контента OpenAI). |
| output_compression | integer | Нет | Сжатие, целое число 0–100, только для вывода `jpeg` / `webp`; чем меньше, тем меньше файл. |
| mask_url | string | Нет | Маска для частичной правки: PNG того же размера, что первый референс, прозрачный там, где нужны изменения. Нужен референс; нельзя сочетать с `markup_url`. Модель следует маске как ориентиру, а не как жёсткой границе. |
| markup_url | string | Нет | Слой разметки: прозрачный PNG с кругами или пометками там, где нужны изменения, поверх первого референса; в промпте скажите, что сделать, например: «сделай вазу в красном круге синей и убери круг». Нужен референс; нельзя сочетать с `mask_url`; до 16,77 мегапикселя. |

`background` может быть `transparent` (используйте с выводом PNG или WebP); `output_format` — `png` (по умолчанию), `jpeg` или `webp`. `n` только 1. Параметр, которого нет в таблице, возвращает 400 `unsupported_image_parameter` при отправке, ничего не списывается; результат приходит как `url`, а `usage` содержит токены и сумму списания за задание.

## Оплата по токенам

При отправке удерживается верхняя граница по размеру, качеству и числу референсов; после генерации задание оплачивается по использованию, которое сообщает OpenAI, а остаток удержания сразу возвращается; неудача возвращается полностью. Цены за 1M токенов:

| Статья | Наша цена | Цена OpenAI |
| --- | --- | --- |
| Вывод изображения | $21.6 | $30 |
| Ввод изображений (референсы) | $5.76 | $8 |
| Ввод текста | $3.6 | $5 |

**Измеренные выходные токены и стоимость (без ввода)**

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

При одном и том же размере и качестве выходных токенов всегда одинаково, независимо от промпта; каждый референс добавляет около 700–1 600 токенов ввода изображений.

## Пропорции, разрешение и размер изображения

Соотношение сторон указывается в `size`, уровень — в `resolution`. Вы получаете оригинал в том виде, как он сгенерирован, без обрезки и масштабирования, в размерах из таблицы ниже: обе стороны кратны 16, а 4K — не больше 3840 px по стороне и около 8,3 мегапикселя.

| Пропорция | 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 |

- Поддерживаются 15 соотношений из таблицы; любое другое возвращает 400 при отправке, ничего не списывается. Если `size` = `auto` и есть референс, изображение следует соотношению, ближайшему к первому референсу; без референса — 1:1. Несколько вытянутых соотношений в 1K меньше минимального числа пикселей модели и рендерятся в увеличенных размерах из таблицы (16:9 — 1088×608).

- `size` может быть и размером в пикселях (например, `1536x1024`) в одном из 15 соотношений: ширина и высота округляются вниз до кратных 16, уменьшаются при превышении предела уровня и увеличиваются до минимума модели (около 655 000 пикселей), если слишком малы. Уровень задаёт `resolution`; без него — длинная сторона: до 1536 — 1K, до 2048 — 2K, больше — 4K. Диапазоны длинной стороны: 1K 512–1536, 2K 2016–2304, 4K 2049–4096; вне их запрос возвращает 400 при отправке, ничего не списывается.

## Качество и исходное разрешение

- Без `quality` изображение рендерится в medium. Качество меняет только токены и цену, но не размер; при `auto` решает модель, удержание считается по `max`, а оплата — по фактическому использованию.

- Если в `quality` указано `1K`, `2K` или `4K`, а `resolution` не передан, это значение считается уровнем разрешения (размер и цена — по этому уровню).

- В часы нагрузки задания ждут в очереди, а не падают сразу; если после долгого ожидания (около 15 минут) изображения нет, задание завершается неудачей с полным возвратом, и его можно отправить снова как есть.

## Изображение из изображения и референсы

- Передайте `image` (одно) или `images` (несколько, до 16; лишние не используются) для режима «изображение в изображение» и опишите в промпте, что изменить. `POST /v1/images/edits` принимает те же параметры.

- Оба эндпоинта принимают только JSON-тело, а не загрузку файлов через multipart, поэтому `images.edit()` из OpenAI SDK напрямую не подойдёт: передавайте ссылки или base64, как в примере ниже.

- Каждый референс — публичная ссылка (http / https), data: URI или base64, до 16 МБ, в формате PNG, JPEG или WebP; референс в другом формате приводит к неудаче задания и полному возврату средств.

- Ссылка должна отдавать само изображение, а не веб-страницу и не адрес за логином или с защитой от хотлинка. Референс, который не удаётся прочитать, отклоняется при отправке с ошибкой 400, где указано, какой именно и почему; задача не создаётся, ничего не списывается.

- Пропорцию результата задаёт `size`, а не референс. Чтобы сохранить исходную пропорцию, укажите её в `size`.

- Референсы мы размещаем у себя и храним 7 дней.

**Изображение из изображения по двум референсам**

```
curl https://kovapi.com/v1/images/generations \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-image-2.6-sunburst-token", "prompt": "Сохрани людей, замени фон на ночной пляж с гирляндами тёплого света", "images": ["https://example.com/people.jpg", "https://example.com/beach.jpg"], "size": "3:4", "resolution": "2K"}'
```

## Статус задачи и поля ответа

`GET /v1/images/jobs/{id}` возвращает эти статусы; все поля описаны в разделе [Асинхронные задачи](https://docs.kovapi.com/ru/guide/async-jobs#fields). Опрашивайте каждые 2–3 секунды или используйте вебхук.

| Статус | Что значит |
| --- | --- |
| queued | В очереди. В ответе есть `queue_position` (сколько задач впереди) и `eta_seconds` (ожидаемое время ожидания). |
| processing | Генерируется. |
| succeeded | Готово. Результат в `data[0].url`, детали оплаты в `usage`. |
| failed | Ошибка. Причина в `error`; зарезервированные кредиты возвращаются полностью. |

Один аккаунт выполняет до 50 задач одновременно; остальные ждут в порядке отправки, а задача, не начавшаяся за 15 минут, завершается ошибкой с полным возвратом. Записи о задачах хранятся 3 дня, ссылки на изображения — 15 дней.

## Сколько ждать

Обычно 20–60 секунд от отправки до результата; 4K, редактирование с несколькими референсами и часы пиковой нагрузки занимают больше, отдельные задания — минуту-две.

## Ошибки и возвраты

Ошибка при отправке сразу возвращается как HTTP 4xx / 5xx: задача не создаётся, ничего не списывается. О неудаче после того, как задача принята, сообщает эндпоинт задачи, а резерв возвращается полностью. Все коды перечислены в разделе [Коды ошибок](https://docs.kovapi.com/ru/guide/errors).

### Ошибки при отправке

| HTTP | code | Причина | Что делать |
| --- | --- | --- | --- |
| 400 | missing_prompt | В запросе к `/v1/images/generations` нет `prompt`. | Добавьте `prompt`. |
| 400 | invalid_request | Не удаётся прочитать референсное изображение (битая ссылка, не изображение, больше 16MB…; в `message` указано, какое и почему), в `/v1/images/edits` нет референсного изображения, тело запроса — не JSON-объект или `n` — не целое число. | Исправьте то, что указано в `message`, и отправьте снова. |
| 400 | model_not_found | ID модели написан с ошибкой, `model` не передан или модель нельзя использовать на этом эндпоинте (например, чат-модель на эндпоинте изображений). | Берите ID модели из `GET /v1/models` или из [справочника API](https://docs.kovapi.com/ru/api). |
| 401 | invalid_api_key | Ключ не существует, удалён или отключён, либо отключён аккаунт. | Проверьте ключ на странице API Keys в консоли. |
| 402 | insufficient_quota | Баланса не хватает, чтобы зарезервировать стоимость этого запроса. Шлюз сначала резервирует максимально возможную стоимость запроса, поэтому ошибка может возникнуть и при всплеске одновременных вызовов. | Если был всплеск запросов, подождите несколько секунд и повторите; в остальных случаях пополните баланс. |
| 429 | rate_limit_exceeded | Превышен лимит запросов в минуту, заданный для этого ключа (считается за последние 60 секунд). Заголовка `Retry-After` нет. | Подождите несколько секунд и повторите или увеличьте лимит ключа в консоли. |
| 503 | model_maintenance | Модель на обслуживании и не принимает запросы; пока идёт обслуживание, другая модель вместо неё не ответит. | Повторите, когда обслуживание закончится; ход работ — на [странице статуса](https://kovapi.com/ru/status). |
| 503 | service_unavailable | Временный сбой на нашей стороне, например при сохранении референсного файла; `/v1/responses` также отвечает 503 с `Retry-After`, когда временно не может принять запрос. | Повторите чуть позже. |

### Неудачные задачи (`status` — `failed`)

| code | Когда возникает | Что делать |
| --- | --- | --- |
| moderation_blocked | Изображение: система безопасности поставщика модели отклонила промпт или референсное изображение (код может быть и `content_policy_violation`). | Перепишите промпт или замените референс; повторная отправка без изменений обычно снова отклоняется. |
| upstream_error | Любая другая ошибка: автоматические повторы не помогли, задача ждала 15 минут и так и не запустилась, поставщик отказал без объяснения причины и т. п.; что именно произошло, указано в `message`. | Обычно повторная отправка проходит успешно. |

## Вебхуки вместо опроса

Добавьте при отправке `callback_url` — как только задача завершится, успешно или с ошибкой, шлюз отправит на этот URL ровно то же, что возвращает эндпоинт опроса; запрос подписан, а при неудачной доставке повторяется. Общий адрес для всего аккаунта можно также задать в консоли, в разделе «Настройки → Вебхуки». [Документация по вебхукам →](https://docs.kovapi.com/ru/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-sunburst-token", "prompt": "Картина маслом: гавань в сумерках, заметные мазки, тёплая палитра", "size": "1:1", "callback_url": "https://your-domain.com/webhook"}'
```