Endpoint OpenAI Image Generation API: какой выбрать

Если вы внедряете генерацию изображений через OpenAI сейчас, самая надежная стартовая поверхность по-прежнему прямой Images API, а не Responses. Для генерации одной картинки используйте POST /v1/images/generations, для правок существующих изображений используйте POST /v1/images/edits, а к Responses с image_generation tool переходите только тогда, когда генерация изображения становится одним шагом внутри более крупного мультимодального или agent workflow.

Это различие важно, потому что текущая документация OpenAI по-прежнему разносит ответ по нескольким страницам. image generation guide объясняет разделение между Images API и Responses API. Images API reference дает сырые пути. image_generation tool guide объясняет, как устроена генерация внутри Responses. А страница Images and vision по состоянию на 23 марта 2026 года все еще говорит, что latest image generation model — это gpt-image-1, хотя текущий каталог моделей показывает уже другую картину.

Поэтому для этого запроса недостаточно просто назвать URL. Нужна более полезная вещь: правило выбора surface, с которого стоит начать именно вашу задачу. Если вы хотите сначала доказать, что можете стабильно получить одну картинку, начинайте с прямого Images API. Если позже появится реальная необходимость встроить генерацию изображения в более широкий reasoning flow, разговорный интерфейс или цепочку tool calls, тогда уже имеет смысл переходить к Responses.

Текущая карта image endpoints OpenAI в одной таблице

Понять текущий image stack OpenAI проще всего, если разделить прямую работу с изображением и мультимодальную оркестрацию через tools.

Эта таблица — самый честный ответ, потому что она повторяет логику текущей документации OpenAI. image generation guide говорит о двух основных путях и для одной картинки направляет к Image API. tool guide нужен для другой ситуации: когда генерация изображения является частью более крупного reasoning workflow.

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

Если вопрос с model ID у вас еще не решен, сначала сравните варианты в локальной статье OpenAI image generation API models. Эта страница намеренно уже: здесь главное не перепутать surface.

Для прямой генерации начинайте с POST /v1/images/generations

Для большинства новых интеграций это лучший первый тест. Текущий Images API reference показывает POST /images/generations как сырой endpoint генерации, что на практике означает вызов https://api.openai.com/v1/images/generations из вашего backend. А в качестве точки опоры по актуальному model choice безопаснее всего использовать страницу GPT Image 1.5, потому что именно она фиксирует текущую image line.

Первый запрос лучше намеренно сделать скучным: один prompt, квадратный размер и текущая основная image model. Этого достаточно, чтобы понять, работают ли API key, project, доступ к модели и форма payload. Гораздо легче локализовать проблему именно так, чем пытаться в первом же эксперименте одновременно решить прозрачный фон, multi-image edit, Responses и формат вывода.

Минимальный cURL выглядит так:

bash
curl https://api.openai.com/v1/images/generations \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-1.5",
    "prompt": "Create a clean editorial illustration of a robot camera operator in a bright studio",
    "size": "1024x1024",
    "quality": "medium"
  }'

В SDK на JavaScript соответствие почти буквальное:

js
import OpenAI from "openai";

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

const result = await client.images.generate({
  model: "gpt-image-1.5",
  prompt: "Create a clean editorial illustration of a robot camera operator in a bright studio",
  size: "1024x1024",
  quality: "medium",
});

Есть и практическая деталь, которую слабые статьи часто пропускают. По текущему Images API reference модели GPT Image по умолчанию возвращают b64_json, а не готовый hosted URL. Это значит, что ваш первый “успех” должен подтверждать не только HTTP 200, но и то, что backend умеет декодировать ответ и сохранять или передавать итоговое изображение. И это еще одна причина начинать именно с прямого endpoint: так самый короткий цикл от запроса до usable output виден лучше всего.

Если вам нужен более широкий набор примеров на JavaScript, Python и cURL, идите дальше в локальную статью OpenAI image generation API example. Эта статья уже по смыслу и концентрируется на выборе endpoint.

Если у вас уже есть входные изображения, используйте POST /v1/images/edits

Многие ищут “image generation endpoint”, а потом выясняют, что реальная задача — не генерация с нуля, а изменение уже существующего изображения. В этом случае лучший текущий маршрут остается тем же — прямой Images API, просто на edit branch.

Текущий Images API reference перечисляет POST /images/edits как endpoint для edit, а основной image generation guide уже показывает современные edit-примеры с GPT Image 1.5 на той же поверхности. Это важно, потому что означает: сам факт редактирования изображения не заставляет вас автоматически переходить в Responses.

Короткий SDK-вариант выглядит так:

js
import fs from "fs";
import OpenAI from "openai";

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

const result = await client.images.edit({
  model: "gpt-image-1.5",
  image: [fs.createReadStream("product-shot.png")],
  prompt: "Keep the product shape, but place it on a clean studio shelf with warm lighting",
  input_fidelity: "high",
});

Стоит упомянуть input_fidelity: "high" даже в статье про endpoints, потому что он показывает: прямой edit route — это не “упрощенная версия”. Это текущая официальная основная поверхность для image editing. Уходить с нее стоит только тогда, когда workflow в целом становится более сложным, а не просто потому, что image task перестает быть совсем простой.

Слабые tutorials часто ошибаются именно здесь. Они сводят любую более сложную image-задачу к Responses, как будто edit, masks и richer controls автоматически требуют tool flow. Это только увеличивает стоимость обучения. Пока ваша задача по сути остается “измени это изображение”, прямой Images API обычно проще и по request shape, и по debugging path.

Если следующий вопрос у вас уже не про endpoint, а про masks, input_fidelity, preservation или multi-image compositing, правильное продолжение — локальная статья OpenAI image editing API. Для этой страницы достаточно закрепить более важное правило: edit — это first-class use case Images API, а не автоматический повод переходить в Responses.

Переходите в Responses только тогда, когда генерация изображения стала частью большего потока

Ценность Responses не в том, что он “новее”, а в том, что он лучше подходит для более крупного workflow. Если вашему продукту нужен основной reasoning model, который читает инструкции, вызывает другие tools, держит conversation state и только на одном из шагов генерирует изображение, тогда image_generation tool действительно становится более подходящей абстракцией, чем прямой endpoint.

Самая частая техническая ошибка здесь — поставить gpt-image-1.5 прямо в верхнеуровневый model у Responses. Текущий image_generation tool guide прямо пишет, что GPT Image модели используются за инструментом, но не являются допустимыми значениями для верхнего model.

Поэтому форма запроса выглядит скорее так:

js
import OpenAI from "openai";

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

const response = await client.responses.create({
  model: "gpt-5",
  input: "Generate a transparent sticker-style icon of a paper airplane for a travel app",
  tools: [{ type: "image_generation", background: "transparent", quality: "high" }],
});

Этот путь корректный, но он решает другую задачу. Он сильнее, когда:

1. один запрос может вернуть и текст, и изображение;
2. генерация картинки — лишь один из нескольких tools;
3. модель должна сама решать, когда генерировать, а когда продолжать reasoning.

Он слабее, когда ваш текущий вопрос всего лишь “с какого endpoint начать”. В таком случае Responses добавляет лишние слои: верхнеуровневую модель, tool invocation, parsing tool output и более косвенную цепочку отладки.

Поэтому правило не такое: “Responses новый, значит лучше”. Правило точнее формулируется так: Responses лучше тогда, когда самой проблемой становится orchestration. Если orchestration пока не является вашей реальной задачей, не усложняйте старт раньше времени.

Если после этой статьи вам нужен более широкий маршрут внедрения, естественным продолжением будет локальная статья OpenAI Image API tutorial.

Несинхронность документации и проверки доступа делают правильный endpoint похожим на неправильный

Это слабейшее место текущей SERP. Многие разработчики думают, что ошиблись с endpoint, хотя реальная проблема — свежесть документации или готовность аккаунта.

Сначала о свежести. На 23 марта 2026 года all-model catalog показывает GPT Image 1.5 как текущую image line, а страница GPT Image 1.5 также ведет себя как current flagship. Но официальная Images and vision по-прежнему говорит, что latest image generation model — это gpt-image-1. Более старый cookbook example тоже использует gpt-image-1.

Это не значит, что официальные docs бесполезны. Это значит, что разные страницы решают разные задачи.

1. Сырые пути смотрим в API reference;
2. Актуальную line и freshness смотрим в all-model catalog и GPT Image 1.5 page;
3. Выбор между Images API и Responses делаем по main guide;
4. К tool guide идем только тогда, когда действительно пишем Responses flow.

Вторая ловушка — доступ. Страница GPT Image 1.5 явно показывает Free not supported и публичные лимиты начиная с Tier 1: 100,000 TPM и 5 IPM. Документ API model availability отдельно говорит, что доступ к gpt-image-1 и gpt-image-1-mini связан с tiers 1 through 5 и в ряде случаев с organization verification. Иными словами, endpoint может быть правильным, но account state — еще нет.

Есть и шум от rollout-истории. В собственном GPT Image 1.5 rollout thread OpenAI есть сообщения о проблемах с доступностью и model-not-found во время rollout. Такие ответы потом долго живут в старых tutorials, форумах и кэшированных snippets.

Поэтому более безопасный порядок debugging такой:

1. сначала подтвердить правильную route: Images API сначала, Responses только при необходимости;
2. затем подтвердить current model default: GPT Image 1.5 как актуальную starting line;
3. потом проверить tier, active org и verification;
4. и только затем переписывать payload или SDK calls.

Если ваша реальная проблема — access, а не surface choice, то правильнее сразу перейти к локальной статье OpenAI image generation API verification. Случайная смена endpoints эту ветку почти никогда не лечит.

Итоговая рекомендация

Если вам нужна короткая и рабочая формула на 23 марта 2026 года, запомните вот что:

• для прямой генерации используйте POST /v1/images/generations;
• для правок по входным изображениям используйте POST /v1/images/edits;
• к Responses + image_generation переходите только тогда, когда картинка — часть более крупного мультимодального процесса;
• сырые пути берите из reference, а свежесть — из model catalog и GPT Image 1.5 page.

Эта последовательность сильнее среднего текущего результата на первой странице, потому что она не просто пересказывает официальные факты, а превращает их в операционное решение. Большинство ranking pages до сих пор заставляют читателя самому сшивать answer из reference pages, help pages и старых examples. Надежнее сделать иначе: сначала выбрать правильную surface, успешно провести минимальный прямой запрос, и только потом добавлять ту сложность, которая действительно нужна вашему продукту.

FAQ

Нужен ли Responses для обычного image editing?

Нет. Для стандартных edit workflows текущая документация OpenAI по-прежнему поддерживает POST /v1/images/edits и client.images.edit() как основной путь. Responses выигрывает только тогда, когда edit становится частью более крупного assistant/agent flow.

Стоит ли по-прежнему использовать gpt-image-1, если он встречается на некоторых официальных страницах?

Не как default для новых интеграций. По состоянию на 23 марта 2026 года all-model catalog и GPT Image 1.5 page фиксируют GPT Image 1.5 как текущую основную line. gpt-image-1 лучше рассматривать как migration или legacy-comparison branch.

Почему запрос может падать, даже если endpoint выбран правильно?

Потому что правильный endpoint и готовый account access — не одно и то же. GPT Image 1.5 page показывает отсутствие Free tier, а guidance по availability по-прежнему связывает часть image access с paid tiers и organization verification. Если маршрут выглядит правильным, сначала проверьте доступ, а уже потом переписывайте код.