GPT Image 2 API и Codex: сначала выберите маршрут

Если вы собираетесь использовать GPT Image 2, первый практический вопрос звучит не «какой пример кода скопировать», а «какая поверхность отвечает за эту задачу». Для прямой генерации или редактирования изображений начинайте с Images API. Если изображение появляется внутри assistant или agent flow, смотрите на Responses и его инструмент image_generation. Если вам нужно создать обложки, схемы, иллюстрации или документационные картинки внутри репозитория, Codex может быть рабочим процессом с файлами и review. Если вам нужен единый gateway, альтернативный биллинг или маршрутизация между несколькими провайдерами, это уже отдельный commercial route.

Путаница возникает потому, что один и тот же model ID встречается в разных поверхностях. Но это не означает, что они используют один endpoint, один формат запроса или одну стоимость. Самые дорогие ошибки обычно выглядят так: разработчик ставит gpt-image-2 в верхний model у Responses, считает Codex usage тем же самым, что OpenAI API billing, или переносит цену gateway в таблицу официальных цен OpenAI. Надежнее сначала выбрать владельца маршрута, а уже потом писать payload.

Карта маршрутов перед кодом

Если продукту нужна одна картинка по prompt, прямой Images API проще и честнее. Он проверяет ровно то, что нужно проверить: API key, project, доступ к модели, качество, размер, output handling и ошибки. Если же пользователь общается с ассистентом, ассистент решает, когда нужна картинка, и затем продолжает текстовый или файловый workflow, Responses подходит лучше. Codex — третий случай: не production endpoint для вашего backend, а repo-local workflow, где запрос, сгенерированный файл, ревизия и публикация живут рядом.

Эта таблица важнее любого отдельного snippet. Она отвечает на вопрос «кто владеет задачей». Images API владеет прямой генерацией и edits. Responses владеет tool orchestration. Codex владеет файловым workflow в репозитории. Gateway владеет своим доступом и счетом. Когда владелец выбран правильно, и документация, и логи, и расчет стоимости становятся намного понятнее.

Прямая генерация и edits: начинайте с Images API

Официальный model ID для GPT Image 2 — gpt-image-2. Если задача формулируется как «сгенерировать изображение» или «изменить изображение по входному файлу», самый чистый старт — Images API. У него узкая поверхность: image endpoint, image model field, предсказуемый output и понятная область ошибок. Это особенно полезно в первой интеграции, когда еще неизвестно, доступна ли модель именно вашему organization, правильно ли настроен project и не нужны ли дополнительные проверки.

Первый запрос лучше сделать намеренно простым. Не смешивайте transparent background, multi-image edit, streaming, Responses tool calls и gateway fallback в одном эксперименте. Проверьте минимальный case, сохраните output, запишите request ID и только после этого расширяйте параметры.

ts
import OpenAI from "openai";

const client = new OpenAI({ apiKey: process.env.OPENAI_API_KEY });

const image = await client.images.generate({
  model: "gpt-image-2",
  prompt: "Create a clean route map for a developer documentation page.",
  size: "1024x1024",
  quality: "medium"
});

Для edits логика такая же. Если центральная задача — получить новое изображение из одного или нескольких входных изображений, оставайтесь в прямой image surface. Responses становится нужным, когда вокруг изображения есть reasoning, dialogue, tool decisions или последующие действия, а не просто потому, что Responses выглядит более современным API.

Есть и учетная реальность: доступ к GPT Image models может зависеть от organization verification. Поэтому в русскоязычной инструкции лучше не писать «работает у всех сразу». Более честная формулировка: проверьте project, organization, model access и billing до production rollout.

Responses нужен для assistant-flow, а не как замена endpoint

Responses с image_generation нужен тогда, когда картинка — только один инструмент внутри более широкого процесса. Например, пользователь просит подготовить концепцию карточки товара, модель сначала уточняет задачу, затем генерирует изображение, затем возвращает текстовую инструкцию по публикации. В таком flow верхний model отвечает за понимание задачи и выбор tools, а image_generation отвечает за картинку.

Именно здесь появляется правило, которое часто ломает первые прототипы: gpt-image-2 не должен быть top-level model у Responses. Верхний model остается text-capable model, а image model задается внутри tool configuration, если ваш SDK и текущая документация это поддерживают.

ts
const response = await client.responses.create({
  model: "gpt-5.4",
  input: "Plan a product launch card and generate one square image for it.",
  tools: [{ type: "image_generation", model: "gpt-image-2" }]
});

Этот маршрут сильнее, когда у вас действительно есть assistant UX. Он хуже как первая проверка image integration, потому что добавляет output parsing, tool result extraction, storage, streaming states and retry behavior. Если продукт пока выглядит как обычная кнопка «generate image», Images API будет дешевле в инженерной сложности.

Codex — это файловый workflow, а не публичный API endpoint

В русскоязычной выдаче Codex часто появляется рядом с GPT Image 2, потому что разработчики показывают, как делать картинки из CLI, agent workspace или локального проекта. Это полезная тема, но ее нельзя смешивать с backend API integration. Codex помогает создать файл в контексте репозитория: обложку статьи, схему, mockup, screenshot-based visual или набор документационных иллюстраций. Он хорош там, где важно сохранить prompt, raw asset, publish asset и review trail.

Но если вы строите product backend, Codex не заменяет Images API и Responses. Backend все равно должен знать route, model ID, quality, size, output ID, storage path, retries, user/project и cost attribution. Codex может ускорить подготовку визуальных материалов для документации, но не должен становиться словом, которым вы называете весь public API contract.

Практическое правило для документации простое: можно написать «Codex workflow», «Images API route», «Responses tool route» и «provider gateway route». Нельзя писать так, будто это один продуктовый endpoint. Именно здесь статья должна быть строже, чем типичные короткие posts: ей нужно защищать читателя от wrong contract, а не только подтверждать, что модель существует.

Стоимость: держите три счета отдельно

Для GPT Image 2 стоимость надо объяснять тремя слоями. Первый слой — официальная цена OpenAI API для requests через Images API или Responses. Второй слой — credits или plan limits внутри Codex/ChatGPT, когда вы создаете assets в рабочем окружении. Третий слой — сторонний gateway, где цена, доступность, refund rules and limits принадлежат provider contract.

Если эти слои смешать, команда получит неправильный бюджет. Gateway price не становится official OpenAI price. Codex credit не становится backend API quota. Официальные примеры цен не должны автоматически переноситься на gateway, особенно если gateway добавляет свою маршрутизацию, конвертацию или поддержку.

Provider route имеет смысл, когда команде нужен единый ключ, локальная оплата, резервный канал, multi-model routing или интеграционная простота. В таком контексте можно упомянуть laozhang.ai как отдельный API gateway path и дать читателю посмотреть docs.laozhang.ai или api.laozhang.ai. Но claims вроде unlimited speed, no ban, guaranteed uptime, refund guarantee или failure-no-charge нельзя писать без текущей проверки.

Что логировать перед production

Какой бы маршрут вы ни выбрали, production integration должна сохранять достаточно данных, чтобы объяснить результат после запроса. Минимальный набор: route, model ID, quality, size, input image count, output format, request ID, output ID, storage path, cost, user/project, retry count, error code and account readiness.

Отдельно зафиксируйте unsupported features. GPT Image 2 сейчас не поддерживает transparent backgrounds. Если ваш UI предлагает transparent background как обычный вариант, вы создаете предсказуемую ошибку. Лучше убрать эту опцию из GPT Image 2 route или направить ее в другой flow, где capability действительно подтверждена.

Также решите, что делать с partial or streaming output. Нужно ли показывать intermediate state, сохранять failed output, списывать повторный запрос на того же пользователя и отправлять event в billing system. Эти детали выглядят как backend work, но именно они отличают usable guide от release recap.

Миграция с GPT Image 1.5 требует повторного выбора route

Если у вас уже есть GPT Image 1.5 или более старый image integration, не ограничивайтесь заменой model string. Сначала выясните, какая поверхность у вас была: direct image endpoint, Responses tool flow, Codex asset workflow или provider gateway. Затем проверьте request fields, output format, storage, transparent background assumption, verification requirement and price attribution.

Локальные соседние материалы вроде OpenAI image generation API endpoint, OpenAI image editing API и OpenAI image generation API curl помогают с общей механикой endpoint. Для GPT Image 2 нужна более узкая проверка: когда модель появляется одновременно в API, Responses, Codex and providers, какой route должен владеть вашим job.

Перед rollout задайте три контрольных вопроса. Пользователь просит одну картинку или просит assistant выполнить задачу? Результат идет в production storage and billing? Каждая price, limit and capability claim проверена по текущему source? Если да, маршрут можно оформлять в production docs.

Часто задаваемые вопросы

GPT Image 2 работает только через Codex?

Нет. Codex — полезный workflow для repo-local assets, но direct generation and edits belong to Images API. Для backend product integration начинайте с API route, а не с Codex terminology.

Можно ли поставить gpt-image-2 как top-level model в Responses?

Не стоит. В Responses верхний model должен понимать задачу и управлять tools. Image generation подключается как tool, где image model belongs to the tool configuration or image route.

Чем OpenAI API price отличается от Codex credits?

OpenAI API price относится к requests через API key. Codex credits или plan limits относятся к использованию Codex workflow. Provider gateway price — третий отдельный слой и должен объясняться только как provider-owned pricing.

GPT Image 2 поддерживает transparent background?

Сейчас нет. Если workflow зависит от transparent background, не обещайте эту capability в GPT Image 2 route and do not expose it as a normal UI option.

Когда нужен gateway?

Gateway нужен, если вам важны unified access, local payment, backup routing, multi-model routing or team billing. Если official OpenAI API already satisfies access, compliance and cost, официальный маршрут проще и прямее.

Чем route guide отличается от обычного endpoint guide?

Обычный guide отвечает, какой path вызвать. Здесь вопрос другой: when GPT Image 2 appears in API, Responses, Codex and gateway contexts, which route owns the job. Неправильный route может дать working demo, но сломать billing, permissions or production explanation.