> ## Documentation Index
> Fetch the complete documentation index at: https://docs.apiyi.com/llms.txt
> Use this file to discover all available pages before exploring further.
# GPT-Image-2 Генерация/редактирование изображений
> Флагманская модель генерации изображений OpenAI gpt-image-2. Нативная поддержка разрешения 2K/4K, автоматические референсные изображения высокого качества, на 20-30% дешевле в том же тарифе. Поддерживает text-to-image, редактирование по референсу, объединение нескольких изображений, инпейнтинг по маске.
Все image API являются **синхронными** — здесь нет ID задачи для опроса, и если ваш клиент отключится, результат будет потерян, при этом запрос все равно тарифицируется. Установите достаточно большой timeout для этой модели; см. [Основы и лучшие практики Image API](/ru/api-capabilities/image-api-best-practices).
## Обзор
**gpt-image-2** — новейшая флагманская модель генерации изображений OpenAI — пришедшая на смену `gpt-image-1.5`. Ключевые улучшения: **любое допустимое разрешение (включая 2K / 3840×2160 4K)**, **автоматический high-fidelity при работе с референсными изображениями**, **на 20-30% дешевле при том же уровне**. Шлюз APIYI полностью совместим с OpenAI Images API — укажите сюда `base_url` официального OpenAI SDK для прямого подключения без кода.
**🎨 Ключевые преимущества**: Нативная поддержка любого допустимого разрешения (макс. 3840×2160 4K) + автоматический high-fidelity при редактировании референсных изображений + стоимость на 20-30% ниже, чем у 1.5, при том же размере и качестве + нативная поддержка китайских prompt. **Лучше всего подходит для production-сценариев, где нужен точный контроль размера/качества, требуется полное соответствие официальному OpenAI API или нужен вывод в 4K**.
`/v1/images/generations` — генерируйте изображения из text prompt с контролем размера / качества / output\_format.
`/v1/images/edits` — загрузка референсных изображений в формате multipart (до 16) + инструкции по редактированию/смешиванию, с поддержкой mask inpainting.
## Почему стоит выбрать официальный релей APIYI для GPT-image-2?
Построен на официальном канале OpenAI и глубоко оптимизирован для корпоративных production-нагрузок по направлениям **надежности**, **стоимости** и **опыта интеграции**:
Строго маршрутизируется через официальный релей OpenAI — запросы и ответы **на 100% идентичны официальному OpenAI**: те же поля, те же коды ошибок, то же поведение модели. Беспроблемное качество, без скрытых переписываний.
Не ограничено **порогами RPM / TPM по уровням Tier** OpenAI. Трафик enterprise-масштаба масштабируется линейно — пакетная генерация и сценарии пиковых нагрузок обрабатываются без труда.
Базовая цена за единицу совпадает с официальной ценой OpenAI. Сочетайте с нашими [бонусными акциями пополнения](/ru/faq/recharge-promotions), чтобы получить **скидку до 15%** — долгосрочные расходы заметно снижаются.
**Не требуется зарубежный сервер или прокси**. Подключайтесь напрямую к `api.apiyi.com` из отечественных дата-центров, домашнего широкополосного интернета или зарубежных узлов — стабильная задержка, без трансграничной перестройки архитектуры.
Легко переключайтесь на модель, созданную методом реверс-инжиниринга [`gpt-image-2-all`](/ru/api-capabilities/gpt-image-2-all/overview) (\$0.03 за изображение, фиксированная цена), или на самый выгодный по стоимости [Nano Banana Pro / 2](/ru/api-capabilities/nano-banana-2-image/overview) — комбинируйте варианты под каждый сценарий.
Наша команда специализируется на production-развертываниях генерации изображений и обладает глубоким опытом в выборе модели, настройке и интеграции — полная поддержка от PoC до production.
## Основные возможности
Поддерживается любой допустимый размер вывода. Пресеты охватывают 1K / 2K / 3840×2160 4K. Пользовательские размеры должны лишь соответствовать базовым ограничениям (стороны кратны 16, соотношение сторон ≤ 3:1).
Редактирование по референсному изображению автоматически включает режим высокой точности. Детализация, сохранение идентичности персонажей и текста значительно улучшены. **Не** передавайте `input_fidelity` (иначе будет ошибка).
Качественный режим 1024×1024 снижается с диапазона \$0.25 у 1.5 до \$0.211/изображение. 2K/4K тарифицируется по token, но также дешевеет — долгосрочная стоимость заметно ниже.
Нативная поддержка prompt на китайском языке. Стабильный рендеринг китайского/английского текста на вывесках, постерах, скриншотах UI. Мелкий текст редко размывается на качестве `high`.
`image[]` массив принимает до 16 референсных изображений. Используйте «image 1 / image 2 / image 3» в prompt, чтобы сослаться на них по порядку загрузки.
Загрузите маску с альфа-каналом. Прозрачные области — это области inpaint, непрозрачные области сохраняются.
Поддерживает png (по умолчанию) / jpeg / webp. Установите `output_compression` для jpeg/webp, чтобы управлять размером файла.
Укажите `base_url` на `https://api.apiyi.com/v1` и вызывайте напрямую с официальным OpenAI SDK — миграция без кода.
## Тарифы
APIYI's `gpt-image-2` (группа по умолчанию) **полностью совпадает с официальной ценой OpenAI из прайс-листа** — скидка вместо этого формируется за счет бонуса за пополнение: **пополните \$100 и получите бонус 10%, до 20%**. 📖 [Узнайте о промоакциях за пополнение](/ru/faq/recharge-promotions).
### Тарификация по количеству token (как в прайс-листе OpenAI)
Token-metered — один запрос = токены входного текста + входного изображения + выходного изображения:
| Позиция тарификации | Цена (за 1M tokens) | Примечания |
| -------------------- | -------------------------- | ---------------------------------------------------------------------------------------------------- |
| Входной текст | \$5.00 | Текстовая часть вашего prompt |
| Входное изображение | \$8.00 | Референсные изображения в запросах редактирования/смешивания, токенизируются по правилам Vision |
| Выходное изображение | \$30.00 | **Основная статья затрат** — число token определяется размером × качеством |
| Кэшированный ввод | Text \$1.25 / Image \$2.00 | Настроено, но при высоких параллельных запросах частота попадания в кэш ограничена — см. [ЧЗВ](#faq) |
**Почему входное изображение дороже?** Входное изображение стоит \$8.00 / 1M tokens — **1.6x** ставки \$5.00 / 1M для входного текста (это собственный прайс-лист OpenAI, а не наценка APIYI). Именно поэтому запросы редактирования / fusion с несколькими изображениями заметно дороже по входной части, чем обычная генерация изображений по тексту: референсные изображения токенизируются в большое число image tokens по правилам Vision, и каждый из этих token уже стоит на 60% дороже text token.
### Справка по стоимости за изображение (официальная таблица)
Типичная стоимость за изображение при предустановленных размерах 1K:
| Качество | 1024×1024 | 1024×1536 | 1536×1024 |
| -------- | --------- | --------- | --------- |
| Низкое | \$0.006 | \$0.005 | \$0.005 |
| Среднее | \$0.053 | \$0.041 | \$0.041 |
| Высокое | \$0.211 | \$0.165 | \$0.165 |
**Примечания к тарификации**:
* Базовые цены совпадают с прайс-листом OpenAI; добавьте [бонус за пополнение](/ru/faq/recharge-promotions) (10% при \$100, до 20%), и ваша эффективная стоимость окажется ниже, чем при прямом обращении
* Для 2K / 4K нет фиксированной цены за изображение — тарификация идет по фактическим input + output tokens
* Запросы на редактирование требуют заметно больше input tokens, чем text-to-image, из-за принудительного high-fidelity
* Потоковая передача (`stream: true` + `partial_images: N`) добавляет по 100 output image tokens за каждый partial
* По сравнению с `gpt-image-1.5` того же размера и качества, `gpt-image-2` примерно на 20-30% дешевле
### Как несколько входных изображений влияют на цену (проверено в июле 2026)
Частый вопрос от клиентов: «Каждое референсное изображение стоит фиксированную сумму, или большие изображения расходуют больше tokens?» Ответ: **важны оба фактора, и количество изображений суммируется строго линейно**. `gpt-image-2` обрабатывает каждое входное изображение в принудительном режиме высокой детализации (`input_fidelity` не настраивается — при его передаче возвращается 400), и каждое референсное изображение преобразуется в image tokens в зависимости от его размеров и aspect ratio. Контролируемые измерения (эндпоинт edits, 2026-07-15):
| Входное референсное изображение | `image_tokens` | Стоимость входа (\$8/M) |
| ------------------------------- | --------------------- | ----------------------- |
| 1 × 512×512 | 1024 | ≈\$0.0082 |
| 1 × 1024×1024 | 1024 | ≈\$0.0082 |
| 1 × 2048×2048 | 1521 | ≈\$0.0122 |
| 1 × 4096×4096 | 1521 | ≈\$0.0122 |
| 1 × 1024×1536 (портрет) | 1536 | ≈\$0.0123 |
| **4 × 1024×1024** | **4096 (= 4 × 1024)** | ≈\$0.0328 |
Три практических правила:
1. **Количество строго линейно**: N референсных изображений ≈ N × tokens одного изображения. 16 референсных изображений при 1024² ≈ 16384 tokens ≈ \$0.13 — тот же порядок величины, что и один вывод `high` (\$0.211), так что в случае слияния нескольких изображений этим уже нельзя пренебрегать.
2. **Размер имеет и нижний предел, и потолок**: квадратные изображения размером 1024² и меньше тарифицируются как 1024 tokens (уменьшение до 512 **ничего не экономит**); 2048² и 4096² оба стоят 1521 tokens (слишком большие изображения перед преобразованием уменьшаются — **потолок действует**). Одно референсное изображение обычно попадает примерно в диапазон 800-1600 tokens с учетом соотношения сторон.
3. **Tokens определяются размерами в пикселях, а не размером файла**: сжатие до 1.5MB помогает со стабильностью и скоростью загрузки, но **не уменьшает image tokens**; наоборот, загрузка исходника на 50MB тоже не раздует ваш счет (действует потолок).
Интуитивная оценка стоимости: при выводе `low` (196 tokens ≈ \$0.006) стоимость входа одного референсного изображения (≈\$0.008) фактически превышает стоимость вывода; при выводе `high` (≈\$0.211) одно референсное изображение составляет лишь около 4%. **Размер и качество вывода всегда сильнее всего влияют на цену** — количество референсных изображений стоит на втором месте.
### Оценка стоимости 2K/4K (экстраполяция по соотношению пикселей, ⚠️ не официальная фиксированная цена)
OpenAI публикует только фиксированную таблицу цены за изображение для размеров 1K — **для 2K/4K нет официальной помодельной цены по размеру**. Приведенная ниже таблица — это собственная экстраполяция APIYI на основе официальных ставок 1K выше, масштабированная по числу пикселей, и она предназначена только для планирования бюджета:
| Качество | 2048×2048 (2K-квадрат) | 2048×1152 (2K-альбомная ориентация) | 3840×2160 / 2160×3840 (4K) |
| -------- | ---------------------- | ----------------------------------- | -------------------------- |
| Низкое | ≈\$0.024 | ≈\$0.008 | ≈\$0.026 |
| Среднее | ≈\$0.212 | ≈\$0.062 | ≈\$0.216 |
| Высокое | ≈\$0.844 | ≈\$0.248 | ≈\$0.870 |
**Это оценка, а не официальная таблица цен.** Метод: возьмите официальную строку 1K с тем же соотношением сторон в качестве базовой, затем линейно масштабируйте по числу пикселей целевого размера относительно этой базы (например, у 2048×2048 в 4 раза больше пикселей, чем у 1024×1024, поэтому оценка стоимости тоже увеличивается в 4 раза). Фактическое число выходных image tokens определяется моделью динамически в зависимости от сложности содержимого — оно не является строго линейным — поэтому **считайте `usage.output_tokens` в вашем фактическом ответе источником истины** (см. «Как проверить реальное количество token для каждого вызова» ниже). Размеры выше 2560×1440 при качестве `high` по-прежнему относятся к официальному экспериментальному уровню, поэтому оценки там могут быть менее точными.
### Чем это отличается от SaaS-подписки / тарификации на основе credit
Вендоры инструментов генерации изображений обычно тарифицируют по одной из двух схем:
* **Ежемесячные планы подписки**: фиксированная ежемесячная плата за квоту «N изображений в месяц». Эта квота рассчитывается исходя из **предположения о сверхпродаже** — вендор закладывает ожидание, что большинство пользователей не израсходует весь лимит, поэтому рекламируемая «стоимость за изображение» — это просто цена плана, деленная на верхний предел квоты, а не то, сколько на самом деле стоит сгенерировать для вас одно изображение.
* **Учёт на основе credit / point**: задачи разного качества и размера переводятся в неочевидные «credits». По сути это тарификация по фактическому использованию, просто переупакованная в единицу credit, которая скрывает реальное потребление token.
APIYI работает по модели **официальный релей + фактическая тарификация по token**: без квоты плана, без слоя абстракции в виде credit. Стоимость каждого вызова — это просто фактическое число input/output token × официальный тариф — точный учет по каждому вызову, без сверхпродажи, характерной для подписки, и без динамики «ограничивать, когда вы превысили лимит».
Компромисс тарификации по фактическому использованию в том, что вам нужно самостоятельно оценивать и отслеживать расход, а не полагаться на фиксированную ежемесячную сумму подписки — зато вы платите только за то, чем реально пользуетесь, без простоя и пустых затрат. Вот как напрямую извлечь реальное число token для каждого вызова из ответа, чтобы вы могли вести такой учет самостоятельно.
### Как проверить фактическое количество token для каждого вызова
И `/v1/images/generations`, и `/v1/images/edits` возвращают поле `usage`, а **token входного изображения и token входного текста возвращаются как отдельные поля** — ничего оценивать не нужно, просто считайте их, чтобы получить точную стоимость каждого вызова. Вот полный объект `usage` из реального запроса на редактирование с одним референсным изображением (зафиксировано в реальном времени):
```json theme={null}
{
"data": [ { "b64_json": "..." } ],
"usage": {
"input_tokens": 848,
"input_tokens_details": {
"image_tokens": 832,
"text_tokens": 16
},
"output_tokens": 196,
"output_tokens_details": {
"image_tokens": 196,
"text_tokens": 0
},
"total_tokens": 1044
}
}
```
| Поле | Значение |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `usage.input_tokens_details.text_tokens` | token, израсходованные текстом prompt, с тарификацией \$5.00 / 1M |
| `usage.input_tokens_details.image_tokens` | token, в которые по правилам Vision преобразуется референсное изображение, с тарификацией \$8.00 / 1M; всегда 0 для обычной генерации изображений по тексту без референсного изображения |
| `usage.input_tokens` | Сумма двух полей выше |
| `usage.output_tokens` | token для сгенерированного изображения, определяемые `quality × size` — это **основная составляющая стоимости**, с тарификацией \$30.00 / 1M, и показатель, за которым нужно внимательно следить в запросах 2K/4K (`output_tokens_details.image_tokens` отражает это; `text_tokens` всегда 0) |
| `usage.total_tokens` | Вход + выход вместе |
Формула стоимости для самостоятельного расчета (точная):
```
cost ≈ input_tokens_details.text_tokens × \$5.00 / 1,000,000
+ input_tokens_details.image_tokens × \$8.00 / 1,000,000
+ output_tokens × \$30.00 / 1,000,000
```
Чтобы посмотреть фактическое использование token и детали тарификации для прошлых вызовов, откройте страницу «Logs» в консоли: 📖 [Как посмотреть журналы вызовов](/ru/faq/call-logs) — в подробном представлении журнала перечислены цены для text-input / image-input / output вместе с их количеством token, что соответствует `usage.input_tokens_details` / `usage.output_tokens_details` из API. Инструмент `image_generation` в Responses API сообщает количество token таким же образом, в `usage.input_tokens` / `usage.output_tokens` — см. [Интеграция инструмента Responses](/ru/api-capabilities/gpt-image-2/responses-image-tool).
## Настройка групп
Канал официального релея `gpt-image-2` предлагает две группы. Переключите в панели управления → **Настройки token → Группа**:
| Группа | Коэффициент тарифа | Когда использовать |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| `Default` | 1.0x | Та же цена, что и прайс-лист OpenAI — первый выбор, когда есть свободная емкость; в часы пик возможны 429 / ограничения по параллельным запросам |
| `image2Enterprise` | 1.2x | Стабильный запасной вариант, когда группа по умолчанию перегружена — с приоритетом по емкости |
**Почему 1.2x?** Он откалиброван по "одноразовому промо-пополнению на \$3,000 с бонусом 20% ≈ прайс-лист OpenAI" — APIYI не берет маржу на этом направлении (не считая налоговых издержек) и ведет его как чистый канал с приоритетом по поставке. Когда группа по умолчанию нестабильна, переключите ваш token на `image2Enterprise`, чтобы переждать всплеск нагрузки.
📖 Проверка стабильности (последний журнал вызовов): [/en/live/2026-04/image2-enterprise-stable](/en/live/2026-04/image2-enterprise-stable)
## Технические характеристики
| Параметр | Значение |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Название модели** | `gpt-image-2` |
| **Скорость** | \~120 секунд (4K high quality приближается к 2 мин) |
| **Разрешение вывода** | Любой допустимый размер (1K/2K/4K, max 3840×2160) |
| **Уровни качества** | `auto` / `low` / `medium` / `high` |
| **Форматы вывода** | `png` (по умолчанию) / `jpeg` / `webp` |
| **Китайские prompt** | ✅ Нативно |
| **За один вызов** | 1 изображение (`n=1`) |
| **Лимит референсных изображений** | 16 (`image[]`) |
| **Лимит размера для каждого изображения** | multipart-файл: менее 50MB каждый (png/jpg/webp); base64 data URL: лимит поля около 20MiB, сохраняйте исходники в пределах 15MB |
| **Inpainting по маске** | ✅ Поддерживается (требуется alpha channel, PNG менее 4MB) |
| **Прозрачный фон** | ❌ Не поддерживается (`background: transparent` errors) |
| **Поле ответа** | `b64_json` (**необработанный base64, без префикса**) |
## Эндпоинты
| Эндпоинт | Назначение | Content-Type |
| ----------------------------- | ---------------------------------------------------------------------------------- | --------------------- |
| `POST /v1/images/generations` | Текст в изображение | `application/json` |
| `POST /v1/images/edits` | Редактирование по референсу / слияние нескольких изображений / масочное inpainting | `multipart/form-data` |
**Выбор домена**: `api.apiyi.com` — основной домен. Другие домены шлюза, такие как `b.apiyi.com` / `vip.apiyi.com`, работают одинаково.
## Справка по размерам
### Предустановленные размеры
| size | Значение | Пиксели |
| ----------- | ------------------------- | ----------------- |
| `auto` | Адаптивный (по умолчанию) | Модель определяет |
| `1024x1024` | Квадратный 1:1 | 1K |
| `1536x1024` | Альбомный 3:2 | 1K |
| `1024x1536` | Книжный 2:3 | 1K |
| `2048x2048` | Квадратный 1:1 | 2K |
| `2048x1152` | Альбомный 16:9 | 2K |
| `3840x2160` | Альбомный 16:9 | 4K |
| `2160x3840` | Книжный 9:16 | 4K |
### Ограничения пользовательского размера
`gpt-image-2` принимает **любой допустимый размер**, который соответствует всем условиям:
1. **Макс. сторона ≤ 3840px**
2. **Обе стороны кратны 16**
3. **Соотношение сторон ≤ 3:1**
4. **Общее число пикселей ∈ \[655,360, 8,294,400]** (\~0.65MP до \~8.3MP)
**Допустимые примеры**: `1600x1200`, `1792x1024`, `2048x1536`, `3200x1800`
**Недопустимые примеры**: `1000x1000` (не кратно 16), `4000x4000` (выше максимума), `3840x1000` (соотношение > 3:1)
Выводы выше `2560×1440` (\~3.69MP) официально помечены как **экспериментальные** и могут показывать колебания качества. Для production лучше использовать предустановки вроде `2048x1152` / `2048x2048` / `3840x2160`.
## Справка по качеству
### Доступные уровни
| quality | Значение | Примечания |
| -------- | -------------------------------- | --------------------------------------------------------------------------------------- |
| `auto` | Автоматически (**по умолчанию**) | Значение, которое используется, когда `quality` опущен — модель выбирает уровень за вас |
| `low` | Низкое качество | Самый быстрый и дешевый — хорошо подходит для черновиков / пакетной обработки |
| `medium` | Среднее качество | Сбалансированный вариант для повседневного использования / финального результата |
| `high` | Высокое качество | Текст, тонкие текстуры, печать — самая высокая латентность и стоимость |
**По умолчанию используется `auto`, а не `medium`.** Если `quality` опущен, это эквивалентно передаче `"quality": "auto"` — модель автоматически выбирает уровень качества, и **OpenAI не гарантирует, что это соответствует `medium`**. Уровень, который в итоге выберет `auto`, непредсказуем и напрямую влияет на стоимость, латентность и стабильность тарификации. **Когда вам нужен контроль над стоимостью и предсказуемость, явно передавайте `low` / `medium` / `high` вместо того, чтобы полагаться на `auto`.**
**Не передавайте устаревшие значения DALL·E `standard` / `hd`.** `quality` принимает только четыре официальных значения enum `low` / `medium` / `high` / `auto`. Устаревшие значения DALL·E 3 `standard` / `hd` ведут себя непоследовательно в разных backend-каналах: иногда они сразу завершаются ошибкой 400 (`invalid_value`), а иногда тихо игнорируются, и запрос выполняется с `auto` (непредсказуемая стоимость). Всегда явно передавайте одно из четырех официальных значений.
**`quality` сильнее всего влияет на цену — больше, чем `size`.** Количество output image token определяется `quality × size`, но `quality` имеет гораздо больший вес: при одном и том же размере переход от `low` к `high` может изменить стоимость за изображение более чем в **30×** (см. таблицу «стоимость за изображение» выше: для 1024×1024 диапазон от `low` \$0.006 до `high` \$0.211). Сначала оценивайте стоимость по `quality`, а затем учитывайте влияние `size`.
## Лучшие практики
**Совет по началу работы: сначала добейтесь, чтобы API работал с `low`, затем масштабируйте**
Мы видели, как новые интеграторы сразу переходят к `quality=high` + высокому разрешению и в итоге ждут **≈ 235 секунд (\~4 минуты) на изображение** — лишь затем подозревая, что API завис. Режим `high` имеет наивысшую сложность inference, а 4K может растянуться почти до 5 минут. **Перед переходом в production сначала выполните сквозную интеграцию с `quality=low`** (auth, SDK, params, timeouts, обработка ошибок), а затем переходите к `medium` / `high` только тогда, когда это действительно требуется по качеству.
Для новых интеграций **начинайте с `quality=low` + фиксированного размера**, чтобы проверить полный цепочку вызовов (auth, params, timeouts, обработка ошибок). `low` работает в несколько раз быстрее, чем `high`, поэтому функциональные проблемы быстро проявляются, не маскируясь большой задержкой.
8 официальных пресетов настроены на стабильную скорость и качество. Пользовательские размеры оставляйте только для действительно необычных соотношений сторон.
Черновики / пакетная обработка → `low`; ежедневное / финальное → `medium`; текст, тонкие текстуры, печать → `high`. **Обратите внимание, что `low` ↔ `high` — это не только визуальная точность, но и скачок сложности inference**, поэтому задержка растет соответственно.
Для финального отображения `output_format=jpeg` + `output_compression=85` работает быстрее, чем PNG, и занимает примерно вдвое меньше места.
Рендеринг текста — сильная сторона, но на нижних уровнях он все равно может размываться. Зафиксируйте `quality=high` для сценариев с вывесками и постерами.
Каждое изображение — до 50MB (на практике сжимайте до 1.5MB); поддерживаются PNG/JPEG/WebP; до 16 изображений; указывайте порядок ссылок с «изображение 1 / изображение 2» в prompt.
Два параметра, которые сильнее всего влияют на задержку, — это **`quality`** и **`size`** — особенно `quality`. Настраивайте тайм-ауты клиента по уровням:
| качество | Рекомендуемый тайм-аут клиента | Наблюдаемая задержка |
| -------- | ------------------------------------- | ---------------------------------------------------------------------------- |
| `low` | ≥ **120 секунд** | обычно 10–40 секунд |
| `medium` | ≥ **240 секунд** | обычно 30–90 секунд |
| `high` | ≥ **600 секунд** (страховочный запас) | 2K/4K выполняется 3–5 минут; длинный хвост наблюдается на уровне 235+ секунд |
**Для режима `high` установите 600s как страховочный тайм-аут** — это позволит учесть очереди, вариативность длинного хвоста и джиттер upstream. Показывайте прогресс в UI; на стороне сервера стоит рассмотреть очередь задач.
При миграции с `gpt-image-1.5`: уберите `input_fidelity` (принудительное высокое качество, при передаче вызовет ошибку); не используйте `background: transparent` (не поддерживается).
## Ошибки и повторные попытки
| Статус | Значение | Рекомендуемое действие |
| ------- | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Неверные параметры (нарушение ограничения по размеру, неподдерживаемое поле и т. д.) | Проверьте соответствие ограничениям по размеру; **не передавайте** `input_fidelity` / `background: transparent`; `invalid_image_file` на endpoint редактирования обычно представляет собой фото с телефона MPO — см. [FAQ](#faq) |
| `401` | Неверный token | Проверьте Bearer Token |
| `403` | Блокировка модерацией контента | Скорректируйте prompt или передайте `moderation: low` |
| `429` | Лимит запросов / недостаточный баланс | Экспоненциальная задержка между повторами |
| `5xx` | Ошибка шлюза / серверной части | Повторите 1–2 раза |
| Timeout | Длинный хвост | Устанавливайте таймаут клиента по `quality`: `low` ≥ **120s** / `medium` ≥ **240s** / `high` ≥ **600s** (высокие + 2K/4K запросы выполняются 3–5 минут; длинный хвост наблюдается после 235+ секунд) |
**Рекомендации для клиента**:
* Устанавливайте таймаут запроса по `quality`: `low` ≥ **120 seconds** / `medium` ≥ **240 seconds** / **`high` ≥ 600 seconds** (страховочная мера — наблюдается 3–5 минут; настройка около 120s/360s приводит к множеству ложных таймаутов)
* **Сначала интегрируйтесь с `quality=low`**, затем переходите к `medium` / `high` по мере реальной необходимости в качестве
* Экспоненциальная задержка между повторами для 5xx и таймаутов (рекомендуется 2 повторные попытки)
* Логируйте заголовок `x-request-id` для поддержки
## Частые вопросы
**Да**. `gpt-image-2` возвращает **сырую base64-строку** (без префикса), в отличие от `gpt-image-2-all`. Два варианта на стороне клиента:
* **Запись в файл**: `base64.b64decode(b64_str)` → записать на диск
* **Отображение в браузере**: `img.src = 'data:image/png;base64,' + b64_str` (добавить префикс вручную)
Если ваш код предполагает поведение из версии 1.5, где префикс уже был добавлен, вы получите поврежденный data URL — обработайте это явно.
`gpt-image-2` **принудительно включает** высокоточное обработку референсных изображений и больше не принимает `input_fidelity`. При миграции с 1.5 просто удалите это поле — замена не нужна.
`gpt-image-2` **не поддерживает** `background: transparent` (будет ошибка). Два обходных варианта:
* Установите `background` в `opaque` (или не указывайте) и выделите прозрачность самостоятельно с помощью PIL / sharp / онлайн-инструментов
* Временно вернитесь к `gpt-image-1.5` для сценариев, где прозрачность действительно нужна
1 изображение (`n=1`). Для N изображений отправляйте N параллельных запросов. Каждый тарифицируется отдельно по token.
Более высокое разрешение и более высокое качество требуют больше output image tokens, поэтому обработка занимает больше времени. **В реальных интеграциях клиентов мы видели, что `quality=high` + высокое разрешение занимает примерно 235 секунд (\~4 минуты) на изображение**, а у `3840×2160` + `high` длинный хвост может растягиваться почти до 5 минут. Рекомендации:
* **Сначала интегрируйтесь с `quality=low`**, чтобы проверить цепочку вызова, а затем повышайте уровень по мере реальной необходимости в качестве
* Настраивайте тайм-аут клиента по качеству: `low` ≥ **120s** / `medium` ≥ **240s** / **`high` ≥ 600s** (страховочный запас)
* Показывайте в UI прогресс «генерация»
* Используйте пресеты 1K 1024×1024 / 1536×1024, когда 4K не нужен
**Она настроена, но не закладывайте скидки за cache в бюджет.** Официальные ставки для cached-input: text \$1.25 / image \$2.00 за 1M tokens, и в канале APIYI кэширование настроено — когда запрос попадает в cache, он тарифицируется по ставке cache.
Один честный нюанс: чтобы поддерживать высокую параллельность, APIYI распределяет запросы по нескольким upstream-аккаунтам OpenAI (один аккаунт OpenAI Tier-5 разрешает только 250 RPM). prompt cache OpenAI не переносится между аккаунтами, поэтому при высокой параллельности запросы с одним и тем же префиксом могут не попасть на тот же аккаунт — **попадание в cache может просто не произойти**.
Хорошая новость: влияние небольшое. Основную стоимость в генерация изображений дают output image tokens (\$30 / 1M); скидка cache применяется только к стороне input, поэтому на итоговую стоимость за изображение она влияет слабо. Планируйте бюджет по полной цене input и считайте любые попадания в cache дополнительной экономией.
Потому что `gpt-image-2` автоматически включает высокоточное обработку референсных изображений, а сами референсы по правилам тарификации Vision превращаются в большой объем input tokens. В редактировании input tokens заметно выше, чем в text-to-image, — закладывайте это в бюджет.
**Причина: `quality` был установлен в `auto` (или не указан).** Нам сообщали о случаях, когда «размер, разрешение и reference images одинаковые, а цена то растет, то падает». При проверке выяснялось, что и `size`, и `quality` были установлены в `auto`.
**Виновник — `quality: auto`**: в auto mode модель **интерпретирует запрос и на лету выбирает другой уровень качества для каждой генерации**. Разный уровень означает разное количество output image tokens, а значит и разную цену. Ниже три реальные записи тарификации с **одинаковым input (по 1061 input tokens)**, но стоимостью, отличающейся в несколько раз:
| Задержка | Input tokens | Output tokens | Стоимость за вызов |
| -------- | ------------ | ------------- | ------------------ |
| 53s | 1061 | 1286 | \$0.055082 |
| 135s | 1061 | **5146** | **\$0.194042** |
| 68s | 1061 | 1287 | \$0.055118 |
Во втором вызове `auto` определился более высокий уровень качества, output tokens выросли до 5146, а цена поднялась примерно в 3.5 раза.
**Исправление: не оставляйте `quality` в режиме `auto` — явно передавайте `low` / `medium` / `high`.** При фиксированном уровне число output tokens и цена для одинакового input становятся стабильными и предсказуемыми. См. раздел «Quality Reference» выше.
The `gpt-image-2` image edit endpoint (`/v1/images/edits`) поддерживает до **16** reference images:
* **multipart/form-data file upload**: каждое изображение должно быть меньше **50MB**, форматы `png` / `jpg` / `webp`
* **base64 data URL**: ограничение длины поля составляет примерно **20MiB** (schema `maxLength: 20971520` — ограничение поля-строки, **не** то же самое, что предел multipart в 50MB), поэтому держите исходные изображения в пределах **15MB**
* **mask file**: отдельно ограничен PNG менее **4MB**
Практический совет: не выкладывайте несколько больших изображений одновременно на максимум — слишком большие тела запросов часто падают на уровне gateway / timeout. Самый надежный вариант — сжимать каждое изображение до **1.5MB или меньше**, а качество вывода не связано с размером входного файла.
Эта ошибка (`code: invalid_image_file`) означает: **N-е референсное изображение не является стандартным файлом png / jpg / webp** (нумерация с 1 — используйте индекс, чтобы найти проблемное изображение).
Самая частая причина — **формат MPO** у фото с телефонов: `.jpg`, полученные напрямую с телефонов серии Huawei Mate, содержат подкадр HDR gain-map и фактически являются многокадровыми JPEG-контейнерами (MPO). Заголовок тот же `FFD8`, и расширение, и команда `file` показывают JPEG — на глаз это невозможно заметить. Проверено в июле 2026: файлы MPO всегда отклоняются, а те же изображения, перекодированные в стандартный JPEG/PNG, успешно проходят **на полном исходном разрешении** (это не связано с размерами, названием поля `image[]` или параметрами `quality`/`size`). Ошибка возвращается на этапе проверки input и **не тарифицируется**.
**Исправление**: перекодируйте через Pillow перед загрузкой (если `Image.open(f).format` возвращает `"MPO"`, требуется преобразование):
```python theme={null}
from PIL import Image
im = Image.open("photo.jpg")
im.load() # for MPO, keeps only the first frame
im.convert("RGB").save("photo_fixed.jpg", quality=92)
```
Полные подробности и способ определения: [API редактирования изображений — требования к формату референсного изображения и предварительная обработка](/ru/api-capabilities/gpt-image-2/image-edit#reference-image-format-requirements-and-preprocessing).
* **Того же размера**, что и оригинал, **формат PNG**, **менее 4MB**
* **Должен иметь alpha channel**: прозрачные участки (alpha=0) = область inpaint, непрозрачные = сохранить
* Применяется только к первому изображению
* Маска — это «мягкая подсказка»: модель может расширять или сужать область вокруг замаскированного региона
| Что выбрать | Когда |
| ----------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **gpt-image-2** (Official) | Нужен точный контроль размера/качества, требуется полное совпадение с официальным OpenAI, нужен вывод 4K, нужна inpainting через маску |
| **gpt-image-2-all** (Reverse) | Нужна фиксированная цена \$0.03/изображение, рендер за 30–60s, минимум параметров, высокая стабильность / китайский текст |
Да — без изменений в коде. Поменяйте `base_url` на `https://api.apiyi.com/v1` и укажите `api_key` в качестве вашего APIYI token:
```python theme={null}
from openai import OpenAI
client = OpenAI(api_key="sk-your-key", base_url="https://api.apiyi.com/v1")
resp = client.images.generate(model="gpt-image-2", prompt="...", size="2048x1152", quality="high")
```
**Нет**. `gpt-image-2` использует официальный синхронный endpoint OpenAI — после отправки запроса он выполняется до завершения, без сигнала «cancel». Даже если клиент отключится, сервер все равно завершит генерацию и спишет средства обычным образом. Тщательно настраивайте client-side timeouts — не считайте, что «отключение = нет списания».
По умолчанию **100 RPM** (100 запросов в минуту). Фактически доступный RPM также динамически корректируется общей параллельностью платформы. Если вашей нагрузке нужно больше, свяжитесь с нами и укажите предполагаемые QPS / RPM — мы сможем выделить дополнительную емкость.
**Нет**. `gpt-image-2` строго повторяет официальный API OpenAI — только синхронный режим. Запрос блокируется, пока не будет получен результат (`high` + 4K в реальности занимает 1–2 минуты). Если вам нужна асинхронная очередь или механизм callback:
* Оберните это сами через очередь задач (Celery / BullMQ и т. д.) на уровне бизнес-логики
* Или используйте [`gpt-image-2-all`](/ru/api-capabilities/gpt-image-2-all/overview) — генерирует за 30–60s, удобнее опрашивать с фронтенда
**Нет**. Встроенная модерация контента OpenAI отклоняет небезопасные / некорректные запросы с ошибкой `400`, и **списание не происходит**. Типичный ответ:
```json theme={null}
{
"status_code": 400,
"error": {
"message": "Your request was rejected by the safety system. ...",
"type": "shell_api_error",
"code": "moderation_blocked"
}
}
```
Другие ошибки без списания: `401` (invalid token), `429` (rate limit). **Тарификация token начинается только после того, как запрос действительно достигает этапа генерации модели (то есть получены `200` + `b64_json`).**
## Связанные документы
* [⚖️ Сравнение официального и обратного вариантов](/ru/api-capabilities/gpt-image-2/vs-gpt-image-2-all) - Руководство по выбору бок о бок
* [Площадка Text-to-Image](/ru/api-capabilities/gpt-image-2/text-to-image) - `/v1/images/generations` интерактивное тестирование
* [Площадка редактирования изображений](/ru/api-capabilities/gpt-image-2/image-edit) - `/v1/images/edits` слияние нескольких изображений + mask
* [Подробный разбор: запуск gpt-image-2](/en/news/gpt-image-2-launch) - Новостная статья
* [Полная документация по интеграции](/ru/api-capabilities/gpt-image-2/overview) - Полная справка по API
* [GPT-Image-2-All (Reverse-Engineered)](/ru/api-capabilities/gpt-image-2-all/overview) - Более дешевая и быстрая альтернатива
* [Сообщество: узлы Luck GPT-Image 2 для ComfyUI](/ru/scenarios/ecosystem/luckgpt2-comfyui) - Вызывайте `gpt-image-2` напрямую в ComfyUI (mask / 5 reference images / custom sizes)
* [Сообщество: навыки APIYI GPT-Image 2](/ru/scenarios/ecosystem/apiyi-gpt-image-skills) - Запускайте из Codex CLI / Cursor / Gemini CLI и других ИИ-инструментов для программирования одной фразой
* [Руководство по API](/ru/api-manual) - Общее руководство по использованию
`gpt-image-2` — это официальный флагман OpenAI, тарифицируемый по token. Если для вас важнее фиксированная тарификация (\$0.03/image) и более быстрая генерация (30–60s), см. [gpt-image-2-all](/ru/api-capabilities/gpt-image-2-all/overview).