GPT Image API: как подключить генерацию изображений

Если приложению нужно получить одно изображение по одному текстовому запросу, начинайте с Image API. Это прямой маршрут: приложение отправляет prompt на POST /images/generations, получает данные изображения и сохраняет их у себя. Responses API стоит рассматривать в другом сценарии — когда редактирование идёт диалогом и состоит из нескольких последовательных шагов. Для одного вызова не нужно притворно собирать разговорное состояние.

Актуальный список моделей и параметры перед релизом проверьте в официальном руководстве по генерации изображений. В руководстве, проверенном 21 сентября 2026 года, для новых интеграций указаны GPT Image 2.5 Sunburst и GPT Image 2.5 Flare; в Image API модель передаётся прямо в поле model. Названия, доступность и цены меняются, поэтому этот выбор стоит хранить в конфигурации, а не считать вечной частью документации.

Минимальный запрос на Python

Установите официальный SDK и передайте ключ через переменную окружения OPENAI_API_KEY. Ключ не должен попадать в исходный код, браузер или логи. Например, в Bash:

export OPENAI_API_KEY="ваш_ключ"
python generate_image.py

В PowerShell переменная задаётся так:

$env:OPENAI_API_KEY = "ваш_ключ"
python .\generate_image.py

Сам SDK установите или обновите перед запуском:

pip install --upgrade openai

Минимальный рабочий сценарий выглядит так:

import base64
import os
from pathlib import Path

from openai import OpenAI


output_path = Path("generated.png")
client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])

result = client.images.generate(
    model="gpt-image-2.5-sunburst",
    prompt="A compact isometric server room, blue status lights, clean technical illustration",
    size="1024x1024",
    quality="medium",
)

if not result.data or not result.data[0].b64_json:
    raise RuntimeError("API returned no base64 image data")

image_bytes = base64.b64decode(result.data[0].b64_json)
output_path.write_bytes(image_bytes)

if not output_path.is_file() or output_path.stat().st_size == 0:
    raise RuntimeError(f"Image was not saved correctly: {output_path}")

print(f"Saved {output_path} ({output_path.stat().st_size} bytes)")

Для GPT Image результатом является base64-строка в data[0].b64_json. Это важная граница формата: временный URL, который встречается в примерах для некоторых других моделей, здесь не нужно ожидать. Сначала декодируйте строку, затем запишите байты в PNG или другой поддерживаемый формат. Справочные поля и актуальные ограничения находятся в Images API reference, а форма вызова SDK — в официальном примере openai-python.

Если после настройки API нужен отдельный пользовательский AI-сервис или подписка, это другой маршрут. Каталог AI-сервисов Amber Market помогает выбрать предложение по его карточке; перед подтверждением заказа нужно проверить доступные способы оплаты и итоговую сумму. Владелец каталога подтвердил оплату через СБП, автоматические списания для заказов не заявлены. Каталог не пополняет OpenAI API, не выдаёт API-ключ и не заменяет расходы API; в проверенном снимке от 10 сентября 2026 года отдельного товара для пополнения OpenAI API не было.

Что меняется для редактирования

Однократное редактирование изображения выполняется через POST /images/edits. В запрос добавляются исходный файл и инструкция, например: «замени фон на белый, сохрани форму объекта». Для последовательности «сделай вариант темнее → убери логотип → верни предыдущую версию» уместно рассмотреть Responses API: разговорный контекст становится частью сценария. Это не означает, что Responses API нужен для каждой картинки; выбор определяется количеством шагов и тем, нужно ли сохранять контекст между ними.

Практически полезно отделить слой генерации от хранения. Функция API-клиента должна вернуть байты или путь к временному локальному файлу, а каталог приложения — решить, куда положить результат, как назвать его и сколько хранить. Тогда замена модели не потребует переписывать загрузку в S3, запись в базу или выдачу файла пользователю.

Проверка результата после запроса

Проверяйте не только отсутствие исключения SDK. Минимальный набор проверок такой:

• в ответе есть data;
• у первого элемента есть непустой b64_json;
• base64 успешно декодируется;
• целевой файл существует и имеет ненулевой размер;
• при необходимости файл открывается библиотекой изображений и соответствует ожидаемому формату.

Последняя проверка полезна в фоновых задачах: процесс мог завершиться после создания пустого файла или записать результат не по тому пути. Для пользовательского запроса также верните клиенту понятный статус, а не внутреннее исключение с ключом или телом ответа API.

Как разбирать типичные ошибки

Обрабатывайте исключения SDK и HTTP-статус ответа. В журнале сохраняйте время, модель, размер, укороченную техническую метку операции и request ID, если SDK или ответ его предоставляет. Сам API-ключ и полный пользовательский prompt, если он может содержать чувствительные данные, в лог не записывайте.

Повтор имеет смысл только для временных проблем: rate limit и серверных ошибок. Используйте ограниченное число попыток и backoff, например задержки 1, 2 и 4 секунды с небольшим случайным разбросом. Повторять без изменения запроса ошибку квоты, неверный ключ, запрещённый запрос или ошибку в параметрах бессмысленно: получится тот же отказ, только чуть позже.

Не смешивайте два разных случая:

1. HTTP-запрос не дошёл или сервер вернул временную ошибку. Здесь повтор допустим, если операция для вашего приложения идемпотентна или вы готовы учитывать возможный двойной расход.
2. Сервер принял запрос, но клиент потерял соединение до получения ответа. Повтор может создать второе изображение и вторую тарифицируемую операцию. Для важных задач сохраняйте собственный job_id, состояние попытки и результат, когда это возможно; одного факта сетевого обрыва недостаточно, чтобы утверждать, что первая генерация не состоялась.

Цена и лимиты

Стоимость зависит от модели, качества, размера и актуальных условий API. В публичном руководстве приведены ориентиры для ряда моделей GPT Image, но это не фиксированный тариф для любого будущего запроса. Перед расчётом себестоимости и production-релизом сверяйте цены, доступность модели, лимиты проекта и требования к изображениям в официальной документации.

API-ключ, баланс API и лимиты проекта относятся к платформе API. Подписка ChatGPT — отдельный продукт с другими условиями. Если в приложении нужна генерация изображений, начинайте с отдельного API-проекта и контролируйте его расходы на своей стороне; пользовательская подписка сама по себе не является способом авторизации этого вызова.

Итого: для одного prompt используйте client.images.generate, проверьте b64_json, декодируйте base64 и сохраните байты. Для редактирования отправляйте исходное изображение через Images API, а для многошагового диалога сопоставьте задачу с Responses API. Остальные решения — модель, размер, качество, retries и хранение — фиксируйте в конфигурации и перепроверяйте по официальной документации перед публикацией.