GPT Image 2.5 | Документация API

# GPT Image 2.5

Generate images with Flare or edit reference images with Sunburst.

POST https://api.apihop.ai/openai/v1/images/generations

Use `gpt-image-2.5-flare` for fast image generation or `gpt-image-2.5-sunburst` for precise editing. Check `GET https://api.apihop.ai/v1/models` for availability with your API key.

## Request

```http
POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
```

```json
{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}
```

| Parameter | Values |
| --- | --- |
| `model` | Required: `gpt-image-2.5-flare` or `gpt-image-2.5-sunburst` |
| `prompt` | Required text describing the image or edit |
| `n` | Integer from 1 to 4; default 1 |
| `size` | `auto`, aspect ratio, or pixel dimensions such as `1600x1200` |
| `resolution` | `1k` (default), `2k`, `4k`; ignored for exact pixel sizes |
| `quality` | `low`, `medium`, `high`, `xhigh`, `max`, `auto` (default) |
| `image_urls` | Up to 16 publicly accessible HTTP(S) image URLs |
| `output_format` | `png` (default), `jpeg`, `webp` |
| `output_compression` | Integer from 0 to 100 for JPEG or WebP |
| `background` | `auto`, `opaque`, `transparent`; transparent requires PNG or WebP |
| `moderation` | `low` (default), `auto` |
| `stream` | `false` (default) for JSON, `true` for SSE completion events |

Supported aspect ratios: `1:1`, `3:2`, `2:3`, `4:3`, `3:4`, `5:4`, `4:5`, `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21`, `3:1`, `1:3`. Exact pixel dimensions must be multiples of 16, have no side above 3840 pixels, an aspect ratio at most 3:1, and 655,360 to 8,294,400 total pixels. For example, square `4k` output is 2880x2880, not 4096x4096.

## Reference Images

```json
{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}
```

References use this JSON generation endpoint. Upload local images to your own storage first. Base64 data URIs, multipart uploads, masks, and a separate `/images/edits` endpoint are outside this model's public contract.

## Response

The HTTP connection waits for completion; clients do not poll an upstream task. JSON responses include final image URLs and available token usage:

```json
{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}
```

With `stream: true`, wait for `image_generation.completed` and `[DONE]` on the same connection. Partial image previews are not guaranteed.

## Pricing

Billing uses actual text input, cached text input, image input, cached image input, and image output tokens. Both variants have the same token prices. The model catalog shows your current price and the separate OpenAI reference price. An image is not a fixed-price unit: prompt length, references, size, quality, and count affect the total. A temporary reservation is reconciled after completion. Choosing an explicit quality makes expected usage clearer.

Invalid parameters return 400; authentication failures return 401; insufficient balance returns 402. An unavailable model returns 404, rate limits return 429, and generation failures return 5xx. Do not automatically resubmit a request whose completion status is unknown.

See [Error Codes and Troubleshooting](https://apihop.ai/en/docs/api-reference/errors) for error codes, streaming failures, and retry boundaries.

Используйте gpt-image-2.5-flare для быстрой генерации изображений или gpt-image-2.5-sunburst для точного редактирования. Проверьте доступность для вашего ключа через GET https://api.apihop.ai/v1/models.

Запрос

http

POST https://api.apihop.ai/openai/v1/images/generations
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

json

{
  "model": "gpt-image-2.5-flare",
  "prompt": "A red ceramic cup on a white table.",
  "size": "1:1",
  "resolution": "1k",
  "quality": "low",
  "n": 1
}

Параметр	Значения
`model`	Обязательно: `gpt-image-2.5-flare` или `gpt-image-2.5-sunburst`
`prompt`	Обязательный текст с описанием изображения или изменения
`n`	Целое число от 1 до 4; по умолчанию 1
`size`	`auto`, соотношение сторон или размеры в пикселях, например `1600x1200`
`resolution`	`1k` (по умолчанию), `2k`, `4k`; игнорируется при точных размерах в пикселях
`quality`	`low`, `medium`, `high`, `xhigh`, `max`, `auto` (по умолчанию)
`image_urls`	До 16 общедоступных HTTP(S) URL изображений
`output_format`	`png` (по умолчанию), `jpeg`, `webp`
`output_compression`	Целое число от 0 до 100 для JPEG или WebP
`background`	`auto`, `opaque`, `transparent`; прозрачность требует PNG или WebP
`moderation`	`low` (по умолчанию), `auto`
`stream`	`false` (по умолчанию) для JSON, `true` для событий завершения SSE

Поддерживаемые соотношения сторон: 1:1, 3:2, 2:3, 4:3, 3:4, 5:4, 4:5, 16:9, 9:16, 2:1, 1:2, 21:9, 9:21, 3:1, 1:3. Точные размеры должны быть кратны 16; ни одна сторона не может превышать 3840 пикселей, соотношение сторон — 3:1, а общее число пикселей должно составлять от 655,360 до 8,294,400. Например, квадратный вывод 4k имеет размер 2880x2880, а не 4096x4096.

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

json

{
  "model": "gpt-image-2.5-sunburst",
  "prompt": "Keep the product and its lettering. Replace the background with a white studio.",
  "image_urls": ["https://example.com/product.png"],
  "resolution": "2k",
  "quality": "xhigh"
}

Референсы используют этот же JSON-эндпоинт генерации. Сначала загрузите локальные изображения в собственное хранилище. URI данных Base64, загрузки multipart, маски и отдельный эндпоинт /images/edits не входят в публичный контракт этой модели.

Ответ

HTTP-соединение ожидает завершения; клиенты не опрашивают задачу вышестоящего провайдера. JSON-ответы содержат итоговые URL изображений и доступные данные об использовании токенов:

json

{
  "created": 1789035000,
  "data": [{"url": "https://example.com/generated-image.png"}],
  "usage": {"input_tokens": 15, "output_tokens": 196, "total_tokens": 211}
}

При stream: true дождитесь image_generation.completed и [DONE] в том же соединении. Частичные предпросмотры изображений не гарантируются.

Стоимость

Оплата рассчитывается по фактическим токенам текстового ввода, кэшированного текстового ввода, ввода изображений, кэшированного ввода изображений и вывода изображений. У обоих вариантов одинаковые цены за токены. Каталог моделей показывает вашу текущую цену и отдельно справочную цену OpenAI. Изображение не является единицей с фиксированной ценой: длина запроса, референсы, размер, качество и количество влияют на сумму. Временное резервирование средств сверяется после завершения. Явное указание качества делает ожидаемый расход понятнее.

Недопустимые параметры возвращают 400, ошибки аутентификации — 401, недостаточный баланс — 402. Недоступная модель возвращает 404, ограничения частоты — 429, ошибки генерации — 5xx. Не отправляйте автоматически повторно запрос с неизвестным состоянием завершения.

Коды ошибок, сбои потоковой передачи и границы повторных попыток описаны в разделе Коды ошибок и устранение неполадок.