# Генерация изображений в OpenAI API: Image API или Responses

> Одно изображение по одному промпту — Image API; правки в диалоге и генерация внутри ассистента — инструмент image_generation в Responses. Примеры на Python.

- Source: https://www.aifreeapi.com/ru/posts/openai-image-api-tutorial
- Language: ru
- Published: 2026-03-22
- Updated: 2026-09-25
- Publisher: AI Free API (https://www.aifreeapi.com)

Короткий ответ: если нужно одно изображение по одному промпту — сгенерировать или отредактировать, — берите **Image API** (`client.images.generate` / `client.images.edit`). Если картинку правят в несколько шагов внутри диалога или генерация — один из инструментов ассистента наряду с поиском и текстом, нужен **Responses API** с инструментом `image_generation`. Так это правило формулирует и сама OpenAI в [руководстве по генерации изображений](https://developers.openai.com/api/docs/guides/image-generation#choosing-the-right-api).

В обоих случаях модель изображения нужно указывать явно. По состоянию на 25 сентября 2026 года для новых интеграций OpenAI рекомендует `gpt-image-2.5-flare` (быстрая повседневная генерация) и `gpt-image-2.5-sunburst` (точные правки). Код, в котором модель не указана или указаны `gpt-image-1`, `gpt-image-1.5`, `gpt-image-1-mini` или DALL·E, в ближайшие месяцы перестанет работать — даты ниже.

Одно условие проверьте до написания кода: Россия не входит в [список стран и территорий, где поддерживается OpenAI API](https://developers.openai.com/api/docs/supported-countries). Подробнее — в разделе про доступ.

## Image API или Responses: чем они отличаются на практике

Оба пути используют одни и те же модели GPT Image и одинаково настраивают размер, качество, формат и сжатие. Различаются они тем, где указывается модель, где лежит результат и за что вы платите.

| | Image API | Инструмент `image_generation` в Responses API |
|---|---|---|
| Где указывается модель изображения | В поле `model` запроса: `model="gpt-image-2.5-flare"` | Только внутри инструмента: `tools=[{"type": "image_generation", "model": ...}]`. Верхнее поле `model` занимает основная текстовая модель, например `gpt-5.5` |
| Что будет без явной модели | По справочнику — `dall-e-2`, который удалён из API 12 мая 2026 года | `gpt-image-1`, который отключается 23 октября 2026 года |
| Где результат | `result.data[0].b64_json` — base64 | Элемент `response.output` с `type == "image_generation_call"`, поле `result` — base64 |
| Несколько картинок за запрос | `n` от 1 до 10 | Параметра `n` нет |
| Правки в несколько шагов | Каждый запрос независим, исходник передаёте заново | `previous_response_id` или ID предыдущего изображения |
| Входные изображения | В `/v1/images/edits`: файлы в multipart или массив `images` с `file_id` / `image_url` | URL, base64 data URL или File ID |
| Что оплачивается | Токены изображения (вход и выход) и текста промпта | То же плюс токены основной модели |

Отсюда практическое правило выбора:

- **Баннер, превью, иллюстрация к статье, пакет картинок по списку промптов** — Image API. Меньше кода, одна модель, понятная стоимость. Для офлайн-обработки больших пакетов через Batch API подходит только `gpt-image-2`: [у моделей 2.5 Batch не поддерживается](https://developers.openai.com/api/docs/models/gpt-image-2.5-flare), а [у gpt-image-2 поддерживается](https://developers.openai.com/api/docs/models/gpt-image-2).
- **Одна правка готового изображения по маске или по референсам** — тоже Image API, эндпоинт `/v1/images/edits`. Маски, несколько референсов и замена старого variations разобраны в статье [OpenAI Image Editing API: правка изображений через images.edit](/ru/posts/openai-image-editing-api).
- **Пользователь просит «сделай фон темнее», потом «а теперь без текста»** — Responses. Контекст предыдущих шагов хранится на стороне API, и модель сама решает, генерировать новую картинку или править старую.
- **Ассистент, который по ходу разговора ищет данные, пишет текст и при необходимости рисует** — Responses, потому что генерация изображения становится одним из встроенных инструментов. Если ваш проект ещё на Chat Completions, учтите: встроенные инструменты OpenAI там не работают, и перед этим шагом стоит прочитать [Chat Completions или Responses API: что меняется в интеграции](/ru/posts/chat-completions-vs-responses-api).

![Три вопроса для выбора между Image API и Responses API и напоминание всегда указывать модель изображения явно](https://www.aifreeapi.com/posts/ru/openai-image-api-tutorial/img/route-choice.webp)

## Какие модели указывать и что отключится в 2026 году

Если в вашем коде или в найденном примере стоит одна из моделей из нижней части таблицы, его придётся переписать. Даты взяты со [страницы отключений OpenAI](https://developers.openai.com/api/docs/deprecations).

| Модель | Статус на 25 сентября 2026 года | Что делать |
|---|---|---|
| `gpt-image-2.5-flare` | Актуальная, быстрая повседневная генерация | Для генерации в новых проектах |
| `gpt-image-2.5-sunburst` | Актуальная, упор на точность правок | Для сценариев, где важны правки |
| `gpt-image-2` | Более ранняя модель, без даты отключения | Оставить в работающей интеграции или ради Batch |
| `gpt-image-1` | Отключается **23 октября 2026 года** | Заменить сейчас |
| `gpt-image-1.5`, `gpt-image-1-mini`, `chatgpt-image-latest` | Отключаются **1 декабря 2026 года** | Заменить до этой даты |
| `dall-e-2`, `dall-e-3` | Удалены из API 12 мая 2026 года | Код уже не работает |

У обеих моделей 2.5 есть снапшоты с суффиксом `-2026-09-08`. Идентификатора `gpt-image-2.5` без суффикса Flare или Sunburst нет. Чем Flare и Sunburst отличаются и какую взять под вашу задачу, разобрано в статье [GPT Image 2.5: Flare или Sunburst, стоимость и работа с API](/ru/posts/gpt-image-2-5).

Отдельно проверьте места, где модель **не указана**. Это две самые незаметные ловушки:

1. **Image API без `model`.** По [справочнику](https://developers.openai.com/api/reference/python/resources/images/methods/generate) поле `model` по умолчанию равно `dall-e-2`, если в запросе нет параметров, которые есть только у GPT-моделей. Но `dall-e-2` удалена, так что запрос без `model` адресован модели, которой больше нет. Точный текст ошибки в документации не приведён.
2. **Инструмент Responses без `model`.** В [справочнике Responses](https://developers.openai.com/api/reference/resources/responses/methods/create) для поля `model` инструмента `image_generation` указано значение по умолчанию `gpt-image-1`. Что произойдёт с таким запросом после 23 октября — ошибка или подмена модели, — в документации не сказано. В официальных примерах на Java и Ruby из руководства по инструменту модель тоже не указана — копировать их без правки нельзя.

Быстрая проверка проекта:

```bash
grep -rnE "gpt-image-1|dall-e|image_generation" --include="*.py" --include="*.js" --include="*.ts" .
```

Каждое найденное `image_generation` без соседнего `"model"` — кандидат на исправление.

## Перед первым запросом: страна, ключ и верификация

**Страна.** России нет в списке поддерживаемых стран и территорий OpenAI API. На той же странице OpenAI предупреждает, что доступ к сервисам или предоставление доступа за пределами перечисленных стран может привести к блокировке или приостановке аккаунта. Список составлен по странам, а не по языку: он касается того, откуда идёт работа с API, а не языка интерфейса или промптов. Официального пути использовать OpenAI API из России нет. Сервисы-посредники с оплатой в рублях — отдельные продукты: их цены, набор моделей и поддержка инструментов Responses относятся к ним, а не к OpenAI.

**Ключ и оплата.** Подписка ChatGPT и оплата API — разные системы, API оплачивается отдельно от Plus или Pro. Нужен API-ключ из консоли разработчика в переменной окружения `OPENAI_API_KEY` и официальный SDK:

```bash
pip install openai        # Python
npm install openai        # Node.js
```

**Верификация организации.** Для моделей GPT Image OpenAI может потребовать пройти API Organization Verification. Если первый запрос вернул ошибку вида «Your organization must be verified», переписывать промпт или код бесполезно — разбор в статьях [GPT Image 2: что делать с ошибкой Your organization must be verified](/ru/posts/openai-image-generation-api-verification) и [GPT Image 2 без проверки организации: какой доступ вам нужен](/ru/posts/gpt-image-2-without-organization-verification).

Примеры ниже собраны по документации и справочнику API OpenAI по состоянию на 25 сентября 2026 года; это документированное использование, а не запись реального запуска. Перед продакшном прогоните их на своём ключе.

## Первый запрос через Image API на Python

Минимальный скрипт: явная модель, квадратный кадр 1024×1024, среднее качество, сохранение в файл.

```python
import base64
from openai import OpenAI

client = OpenAI()  # ключ берётся из OPENAI_API_KEY

result = client.images.generate(
    model="gpt-image-2.5-flare",
    prompt="A watercolor lighthouse on a rocky shore at dawn, soft pastel light",
    size="1024x1024",
    quality="medium",
)

image_b64 = result.data[0].b64_json
with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(image_b64))

print(result.usage)  # сколько токенов ушло на этот кадр
```

Запрос считается успешным, если рядом со скриптом появился `lighthouse.png`, который открывается как обычная картинка. Сложные промпты могут обрабатываться до двух минут, поэтому не ставьте в HTTP-клиенте короткий таймаут.

Тот же запрос на Node.js (файл `.mjs`, чтобы работал `await` верхнего уровня):

```js
import fs from "node:fs";
import OpenAI from "openai";

const client = new OpenAI();

const result = await client.images.generate({
  model: "gpt-image-2.5-flare",
  prompt: "A watercolor lighthouse on a rocky shore at dawn, soft pastel light",
  size: "1024x1024",
  quality: "medium",
});

fs.writeFileSync("lighthouse.png", Buffer.from(result.data[0].b64_json, "base64"));
```

Что важно знать о результате:

- **Модели GPT Image всегда возвращают base64.** Параметр `response_format` для них не поддерживается, поля `url` в ответе нет. Ссылки, которые «живут 60 минут», выдавали только DALL·E-модели, и вместе с ними этот вариант ушёл. Если после генерации нужна ссылка, загрузите файл в своё хранилище.
- **Несколько вариантов за раз** — `n=4` (допустимо от 1 до 10), затем обойти `result.data` в цикле.
- **Формат и сжатие** — `output_format="jpeg"` или `"webp"` и `output_compression` от 0 до 100. JPEG генерируется быстрее PNG, если прозрачность не нужна.
- **Размер.** Рекомендуемые размеры — `1024x1024`, `1536x1024`, `1024x1536`. Произвольный `WIDTHxHEIGHT` допустим, если стороны кратны 16, соотношение сторон от 1:3 до 3:1, а общее число пикселей от 655 360 до 8 294 400. Почему, например, `1024x576` не проходит, объясняет статья [GPT Image 2: почему size 1024x576 недопустим и как получить нужный файл](/ru/posts/gpt-image-2-invalid-size).
- **Прозрачный фон** — `background="transparent"` вместе с PNG или WebP; JPEG прозрачность не поддерживает. Проверка результата — в статье [GPT Image 2 и 2.5: прозрачный фон в PNG и WebP](/ru/posts/gpt-image-2-transparent-background).

Правка через Image API устроена так же, только вызывается `client.images.edit` с моделью, файлами `image=[open("photo.png", "rb")]` и промптом. Для сценариев, где важна точность правок, OpenAI советует Sunburst.

## Тот же результат через Responses и инструмент image_generation

В Responses запрос обрабатывает основная текстовая модель, а изображение рисует вызванный ею инструмент. Поэтому моделей две, и каждая стоит в своём поле:

```python
import base64
from openai import OpenAI

client = OpenAI()

response = client.responses.create(
    model="gpt-5.5",  # основная текстовая модель, не модель изображения
    input="Draw a watercolor lighthouse on a rocky shore at dawn",
    tools=[{
        "type": "image_generation",
        "model": "gpt-image-2.5-sunburst",  # без этой строки будет gpt-image-1
        "size": "1024x1024",
        "quality": "medium",
    }],
    tool_choice={"type": "image_generation"},  # вызвать инструмент обязательно
)

calls = [item for item in response.output if item.type == "image_generation_call"]
if not calls or not calls[0].result:
    raise RuntimeError("В ответе нет image_generation_call или result пустой")

call = calls[0]
print(call.status, call.revised_prompt)
with open("lighthouse.png", "wb") as f:
    f.write(base64.b64decode(call.result))
```

Здесь каждая строка закрывает конкретную ошибку:

- **`model` внутри инструмента.** Модели изображений нельзя ставить в верхнее поле `model` запроса Responses: их страницы помечают `v1/responses` как неподдерживаемый эндпоинт. Без `model` в инструменте срабатывает значение по умолчанию `gpt-image-1`.
- **Какая основная модель подходит.** Список поддерживаемых моделей в [руководстве по инструменту](https://developers.openai.com/api/docs/guides/tools-image-generation) устарел: в нём нет `gpt-6-astra`, которую используют примеры той же страницы. По формулировке OpenAI, инструмент должны поддерживать `gpt-5` и более новые модели; для выбранной модели проверьте её страницу в [каталоге моделей](https://developers.openai.com/api/docs/models).
- **`tool_choice`.** Без него основная модель сама решает, рисовать ли, и может ответить только текстом. Если картинка нужна в каждом запросе, вызов инструмента лучше сделать обязательным.
- **Проверка результата.** Элемента `image_generation_call` может не оказаться, а его `result` может быть `null`; у вызова есть `status` (`completed`, `failed` и промежуточные). Код должен проверять оба условия, а не брать `[0]` вслепую.
- **`revised_prompt`.** Основная модель переписывает ваш промпт перед генерацией. Если картинка вышла не такой, как ожидалось, сначала посмотрите это поле.

![Схема запроса к Responses API: основная модель gpt-5.5, модель gpt-image-2.5-sunburst внутри tools и tool_choice; результат в image_generation_call или его отсутствие](https://www.aifreeapi.com/posts/ru/openai-image-api-tutorial/img/responses-flow.webp)

Настройки инструмента повторяют Image API — `size`, `quality` (у моделей 2.5 дополнительно `xhigh` и `max`), `output_format`, `output_compression`, `background`, `moderation`, `partial_images` — плюс `action`: `auto` (по умолчанию), `generate` или `edit`. Параметр `input_fidelity` у моделей 2.5 описан противоречиво, его лучше не передавать.

Изображения на вход инструмент принимает тремя способами: по полному URL, как base64 data URL или по File ID, полученному через Files API. В руководстве OpenAI именно приём File ID и многошаговые правки названы тем, что Responses добавляет к Image API.

## Многошаговые правки: previous_response_id или ID изображения

Правка «продолжи с того же места» делается одним из двух документированных способов. Первый — сослаться на предыдущий ответ:

```python
follow_up = client.responses.create(
    model="gpt-5.5",
    previous_response_id=response.id,
    input="Now make it an oil painting, keep the composition",
    tools=[{
        "type": "image_generation",
        "model": "gpt-image-2.5-sunburst",
        "action": "edit",  # править изображение из контекста, а не рисовать новое
    }],
)
```

Второй — передать во входе ID конкретного вызова генерации вместе с новым сообщением:

```python
follow_up = client.responses.create(
    model="gpt-5.5",
    input=[
        {"role": "user", "content": [{"type": "input_text", "text": "Now make it an oil painting"}]},
        {"type": "image_generation_call", "id": call.id},
    ],
    tools=[{"type": "image_generation", "model": "gpt-image-2.5-sunburst"}],
)
```

Результат извлекается так же, как в первом запросе, — с проверкой `image_generation_call` и `result`. В официальных примерах `tools` с моделью изображения передаётся заново в каждом запросе цепочки — делайте так же, иначе рискуете получить значение по умолчанию.

Три вещи, о которых стоит знать заранее:

- **Цепочка не бесплатна.** При `previous_response_id` все входные токены предыдущих ответов цепочки снова оплачиваются как входные.
- **Ответы хранятся.** По умолчанию Responses сохраняет ответы для состояния приложения 30 дней; `store=False` это отключает.
- **`referenced_image_ids` в текущей документации нет.** Это имя не встречается ни в руководствах по генерации изображений, ни в справочнике Responses. Для продолжения правки используйте `previous_response_id` или элемент `image_generation_call` с `id`, как выше.

## Сколько стоит запрос в Image API и в Responses

У моделей 2.5 и `gpt-image-2` одинаковые ставки за токены ([страница цен](https://developers.openai.com/api/docs/pricing)): $30 за 1 млн токенов вывода изображения, $8 за 1 млн входных токенов изображения, $5 за 1 млн входных текстовых токенов. Одинаковая ставка не означает одинаковую цену кадра: при одном и том же уровне качества модели тратят разное число токенов.

Ориентир по калькулятору OpenAI — только вывод изображения, кадр 1024×1024, без токенов промпта:

| Модель и качество | Оценка за кадр |
|---|---|
| GPT Image 2.5, `medium` | около $0,013 |
| GPT Image 2.5, `high` | около $0,053 |
| `gpt-image-2`, `medium` | около $0,053 |

Разница между путями такая:

- **Image API** — только токены изображения и промпта.
- **Responses** — то же плюс токены основной модели: она читает промпт, переписывает его и формирует ответ. На странице цен OpenAI отдельной платы за вызов инструмента генерации изображений нет; токены встроенных инструментов оплачиваются по ставкам выбранной модели.
- **Потоковая выдача** (`partial_images` от 1 до 3) добавляет 100 токенов вывода изображения за каждый промежуточный кадр: 100 × $30 / 1 000 000 = $0,003. Промежуточных кадров может прийти меньше запрошенного, если финальный готов раньше.

Реальный расход смотрите в поле `usage` ответа. Бюджет на месяц и сравнение уровней качества — в статье [Сколько стоит изображение в OpenAI API: GPT Image 2.5 и GPT Image 2](/ru/posts/openai-image-generation-api-pricing).

## Ошибки: что повторять, а что нет

- **`image_generation_user_error`** — ошибка, которую исправляет сам запрос. Автоматически не повторяйте: измените промпт или входные изображения. Для программной обработки ориентируйтесь на `error.code`.
- **`moderation_blocked`** — частный случай той же ошибки; в ответе может быть объект `moderation_details` со стадией и категориями. Параметр `moderation="low"` ослабляет фильтр, но не отключает его.
- **Лимиты запросов и ошибки сервера** — повторяйте с нарастающей паузой. Ошибки квоты автоматически не повторяйте.
- **Ответ Responses без картинки** — проверьте `tool_choice`, наличие `model` в инструменте и `status` вызова.
- **Ошибка верификации организации** — см. раздел про доступ выше.

OpenAI советует обрабатывать сбои генерации как любые ошибки API: смотреть HTTP-статус или тип исключения SDK и записывать в лог request ID.

## Частые вопросы

### Будет ли работать старый код с DALL·E или gpt-image-1?

Код с `dall-e-2` и `dall-e-3` не работает с 12 мая 2026 года. `gpt-image-1` отключается 23 октября 2026 года, `gpt-image-1.5`, `gpt-image-1-mini` и `chatgpt-image-latest` — 1 декабря 2026 года. Замените модель на `gpt-image-2.5-flare` или `gpt-image-2.5-sunburst` и проверьте инструменты Responses, где модель не указана.

### Можно ли получить ссылку на картинку вместо base64?

От OpenAI — нет: модели GPT Image возвращают только base64, `response_format="url"` для них не поддерживается. Декодируйте base64 и сохраните файл сами.

### Можно ли поставить gpt-image-2.5-flare в верхнее поле model у Responses?

Нет. Верхнее поле занимает основная текстовая модель, а модель изображения указывается в `tools=[{"type": "image_generation", "model": ...}]`.

### Как получить несколько изображений за один вызов?

В Image API — параметром `n` от 1 до 10. У инструмента Responses параметра `n` нет, и гарантированного способа получить ровно несколько картинок за вызов документация не описывает; для пакетов удобнее Image API.

### Можно ли пользоваться OpenAI API из России?

Россия не входит в список поддерживаемых стран OpenAI API, а доступ из неподдерживаемых стран, по условиям OpenAI, может привести к блокировке аккаунта. Официального способа работать с API из России нет.