# GPT Image 2.5 Sunburst — /images/generations

Генерация изображений (асинхронно, через задачи) на базе GPT Image 2.5 Sunburst — второй стилевой ветки: то же поколение и цена, что у Flare, но с более выраженным зерном и мазком кисти. Использование идентично Flare: промпт для «текст в изображение», референс в `image` или /v1/images/edits для «изображение в изображение», затем опрос id задачи.

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

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

## Тело запроса
| Параметр | Тип | Обязательный | Описание |
| --- | --- | --- | --- |
| `model` | string | Да | Model ID, here gpt-image-2.5-sunburst. |
| `prompt` | string | Да | Текстовый промпт с описанием изображения. |
| `size` | string | Нет | Соотношение сторон результата. Рекомендуется передавать соотношение — 1:1, 3:4, 2:3, 9:16, 4:3, 3:2, 16:9 — тогда модель рендерит нативно именно в этом соотношении, без обрезки объекта. Также принимаются размеры в пикселях (например, 1024x1024, 1024x1536, 1536x1024). По умолчанию 1:1 (квадрат). |
| `n` | integer | Нет | Количество изображений, по умолчанию 1. |
| `image` | string | Нет | Изображение в изображение: референсное изображение в виде публичного URL, data: URI или необработанного base64. Если это поле передано, запрос выполняет полноценное изображение-в-изображение с сохранением идентичности объекта в выбранном соотношении и размере (размер/соотношение) — эквивалентно вызову /v1/images/edits. |
| `images` | array | Нет | Множественные референсные изображения (до 8; рекомендуется ≤4 для согласованности объекта): передайте массив строк, либо массив объектов [{"image_url": "..."}]; каждый элемент — публичный URL, data: URI или base64. Запускает мультиреференсное изображение-в-изображение (объединяя объекты и стиль нескольких референсов) — эквивалентно множественному вводу изображений в /v1/images/edits. Для одного референса подходит и поле image выше. |

## Пример запроса
```bash
# 1) submit -> 202 {"id":"img_...","status":"queued"}
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "gpt-image-2.5-sunburst", "prompt": "a serene ink-wash poster, lots of negative space", "size": "1024x1536"}'
# 2) poll until status=succeeded
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

## Ответ
```json
{
  "id": "img_3f9a...c2",
  "object": "image.generation.job",
  "status": "queued",
  "model": "gpt-image-2.5-sunburst"
}
```

## Редактирование изображений (по изображению)
Редактирование изображений (по изображению): укажите референс в поле `image` (публичный URL, data: URI или base64), чтобы получить настоящий i2i с сохранением идентичности — модель перегенерирует изображение с учётом выбранного размера и соотношения сторон. Эквивалентно вызову /v1/images/edits.

```bash
curl https://nezhagate.com/v1/images/generations -H "Authorization: Bearer YOUR_API_KEY" -H "Content-Type: application/json" -d '{"model": "gpt-image-2.5-sunburst", "prompt": "change the background to a starry sky", "image": "https://example.com/ref.png", "size": "3:4"}'
```

## Задачи генерации изображений (отправка → опрос результата)
Рендеринг изображения обычно занимает 1–3 минуты, поэтому эндпоинты изображений работают только через задачи: отправка запроса сразу возвращает job id (HTTP 202); по этому id нужно опрашивать результат — сервер продолжает рендеринг даже при перезапуске, так что изображение никогда не теряется. То же самое для text-to-image и image-to-image. (Старое поле "async": true больше не нужно; оно принимается, но игнорируется.)

```bash
# Шаг 1 · Отправьте задачу (сразу возвращается job id, HTTP 202)
curl https://nezhagate.com/v1/images/generations -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' -d '{"model": "gpt-image-2.5-sunburst", "prompt": "an ink-wash poster", "size": "3:4"}'
# Шаг 2 · Опрашивайте результат (каждые 2–3s, пока status не станет succeeded)
curl https://nezhagate.com/v1/images/jobs/img_3f9a...c2 -H 'Authorization: Bearer YOUR_API_KEY'
```

status принимает одно из значений: queued / processing / succeeded / failed. При успехе ответ содержит data[].url. Опрашивать задачу может только аккаунт, который её создал. Эндпоинты изображений всегда асинхронны — отправка возвращает job id; поле "async": true принимается только для обратной совместимости и игнорируется.