OpenAI Image Generation API Example: актуальные примеры на JavaScript, Python и cURL

Если вам сегодня нужен OpenAI image generation API example, самый надежный старт — Images API с gpt-image-1.5. По состоянию на 23 марта 2026 года это остается самым прямым путем для простой генерации изображения. Переходить на Responses API стоит только тогда, когда генерация изображения является инструментом внутри более крупного мультимодального workflow.

Эта тема выглядит запутанной не потому, что SDK сложный, а потому, что ответ разбросан по нескольким страницам. Основной image generation guide показывает прямую генерацию и редактирование. Гайд по tool image_generation показывает вариант через responses.create(). А справочник Images API фиксирует точные endpoint и схему запроса. Если прочитать только одну страницу, очень легко скопировать рабочий фрагмент кода в неправильную поверхность API.

Самая безопасная последовательность проста: сначала запустите один прямой запрос, получите картинку, сохраните возвращенный base64 на диск, и только потом добавляйте editing, transparency, compression или streaming. Если продукту позже действительно понадобятся conversation state, tools и мультимодальная оркестрация, тогда имеет смысл перейти на Responses.

Самый быстрый рабочий пример OpenAI image generation API

Для этого запроса лучший старт — прямой Images API. Актуальный endpoint — POST /v1/images/generations, а самый разумный текущий модельный идентификатор для нового примера — gpt-image-1.5. Если вам нужно просто отправить запрос и получить картинку, не надо усложнять первую проверку агентным workflow.

Полезная ментальная модель выглядит так:

• отправляете prompt
• получаете изображение в base64
• декодируете
• сохраняете локально

Простейший пример на JavaScript:

js
import fs from "fs";
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",
});

const imageBase64 = result.data[0].b64_json;
const imageBuffer = Buffer.from(imageBase64, "base64");
fs.writeFileSync("openai-image-example.png", imageBuffer);

То же на Python:

python
from openai import OpenAI
import base64

client = OpenAI()

result = 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",
)

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

with open("openai-image-example.png", "wb") as f:
    f.write(image_bytes)

И вариант на 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"
  }' \
  | jq -r '.data[0].b64_json' \
  | base64 --decode > openai-image-example.png

Если у вашей системы нет base64 --decode, используйте эквивалентный флаг. На macOS это обычно base64 -D.

Это лучший пример по умолчанию, потому что он объясняет актуальный прямой контракт, не заставляя читателя раньше времени разбираться в tools и orchestration. Еще одна деталь, которую старые туториалы часто пропускают: GPT image models по умолчанию возвращают base64-данные, а не ссылку на hosted image. Поэтому хороший стартовый пример обязан показать не только запрос, но и декодирование результата.

Когда выбирать Images API, а когда Responses

Если вам нужно просто генерировать или редактировать изображения, прямой Images API понятнее и проще в отладке. Если же вы строите assistant, который работает с текстом, tools, изображениями и контекстом, тогда Responses становится логичнее.

Главное правило, которое page one до сих пор не объясняет достаточно прямо: не начинайте с Responses только потому, что он кажется более новым. Начинайте с Responses тогда, когда продукту действительно нужна мультимодальная оркестрация. Иначе вы только усложняете первый рабочий пример.

Есть и второй типичный промах. В маршруте Responses поле model должно быть чем-то вроде gpt-5, а не gpt-image-1.5. Гайд по tool прямо объясняет, что image_generation вызывает GPT Image под капотом, а верхнеуровневая модель все равно отвечает за reasoning и решение, когда использовать tool.

От этого зависит и порядок отладки. В прямом Images API вы в первую очередь проверяете access, request shape и сохранение файла. В Responses появляется еще одна плоскость: вызвался ли tool, как вы парсите output и как соотносятся верхнеуровневая модель и image tool. Поэтому первая рабочая версия в этой статье остается на прямом пути.

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

Перед запуском примера проверьте доступ и model IDs

Многие ошибки вида «этот пример не работает» на самом деле не имеют отношения к коду. На 23 марта 2026 года страница GPT Image 1.5 показывает Free not supported, а также указывает Tier 1 starting at 100,000 TPM and 5 IPM. То есть запрос может падать еще до того, как ваш код вообще станет релевантен.

Есть еще один важный нюанс. Статья API model availability by usage tier and verification status говорит, что gpt-image-1 и gpt-image-1-mini доступны для API-пользователей tiers 1 through 5, при этом часть доступа зависит от organization verification. Поэтому если вы скопировали валидный на вид пример, а он все равно не запускается, сначала смотрите на account surface, а не на SDK.

Правильный порядок проверки такой:

1. Установить актуальный SDK.
2. Подтвердить OPENAI_API_KEY.
3. Убедиться, что аккаунт находится на совместимом usage tier.
4. Проверить активную организацию.
5. Убедиться, что используется актуальный model ID.
6. И только потом менять prompt или параметры.

Node.js:

bash
npm install openai

Python:

bash
pip install openai

Если вы только что завершили verification, но по-прежнему видите ошибки вроде not verified, статья API Organization Verification рекомендует подождать до 30 минут, создать новый API key, обновить сессию и убедиться, что активна правильная организация. Для этого ключевого запроса это не мелкая деталь, а одна из первых реальных веток отказа.

Практическое правило здесь простое: сначала отлаживайте доступ, потом форму запроса, и только потом качество prompt. Многие разработчики делают ровно наоборот.

Как добавить editing и output controls, не меняя API

Когда базовый пример уже работает, не меняйте поверхность API без причины. Editing, transparent background и output tuning по-прежнему относятся к прямому пути Images API.

Актуальный пример редактирования:

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-photo.png"),
    fs.createReadStream("logo.png"),
  ],
  prompt: "Add the logo to the product box as if it were printed on the packaging.",
  input_fidelity: "high",
});

const imageBase64 = result.data[0].b64_json;
fs.writeFileSync("product-with-logo.png", Buffer.from(imageBase64, "base64"));

Параметр input_fidelity: "high" стоит использовать осмысленно. Официальный guide объясняет, что он лучше сохраняет детали входного изображения, но увеличивает image-token cost. Используйте его, когда верность исходнику действительно важна, а не как автоматический default для каждой первой попытки.

Та же прямая API поддерживает:

• size: для первого теста надежнее всего 1024x1024
• quality: medium — хороший старт для валидации пути
• background: transparent для GPT image models в png и webp
• output_format: jpeg или webp, когда важны размер файла и latency
• output_compression: когда вы специально хотите контролировать сжатие JPEG или WebP

Самое полезное правило — сделать первый запрос скучным. Квадратное изображение средней quality помогает изолировать access, payload, decoding и запись файла. Когда это работает, можно добавлять transparency, high quality или multi-image edits.

Если перед продакшеном вы хотите отдельно понять economics, следующий логичный шаг — русская версия гайда по pricing для OpenAI image generation API.

Когда действительно нужно переключаться на Responses

Если ваш продукт уже перешел от «сгенерировать одну картинку» к «assistant рассуждает, вызывает tools и иногда возвращает изображение», тогда Responses становится правильной абстракцией.

js
import fs from "fs";
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",
    },
  ],
});

const imageBase64 = response.output
  .filter((item) => item.type === "image_generation_call")
  .map((item) => item.result)[0];

fs.writeFileSync("paper-airplane.png", Buffer.from(imageBase64, "base64"));

Этот пример корректен, но он решает другую задачу. Он хорош, когда генерация изображения — часть более широкой interaction loop. Он не становится лучшим только потому, что использует Responses.

Используйте Responses, когда:

• один и тот же запрос может возвращать и текст, и изображение
• генерация изображения — это tool внутри assistant workflow
• модель должна сама решать, когда генерировать изображение
• визуальный шаг должен существовать рядом с другими tools

Оставайтесь на прямом Images API, когда:

• нужен самый короткий onboarding
• backend endpoint делает одну image-задачу
• вы отлаживаете generation или editing
• вам нужен чистый пример для коллеги или junior developer

Troubleshooting: ошибки, которые старые туториалы часто пропускают

Первая ошибка — использовать старый model name, потому что старый tutorial до сих пор rank'ится. В этой выдаче все еще всплывают legacy-материалы, включая GPT Image 1 и даже DALL·E-эпоху. Если вы публикуете новый example сегодня, стартовым именем должен быть gpt-image-1.5.

Вторая ошибка — ставить gpt-image-1.5 прямо в поле model у Responses. Tool guide однозначен: GPT Image models находятся за tool image_generation, а верхнеуровневая модель остается чем-то вроде gpt-5.

Третья ошибка — принимать access error за code error. Если в ответе вы видите проблемы availability, permission или verification, сначала проверяйте tier и организационную verification, а не payload. Для более детального разбора этой ветки у нас есть русская версия гайда по verification.

Четвертая ошибка — ожидать старое DALL·E-поведение. Для GPT image models прямой Images API по умолчанию возвращает base64. Именно поэтому хороший минимальный пример обязан показывать decode-and-save.

Пятая ошибка — пытаться решить все требования в первом запросе. Разработчики часто добавляют portrait size, transparency, high quality, multi-image edits и assistant orchestration еще до того, как доказали, что базовый прямой путь вообще работает. Это плохой порядок. Сначала подтвердите прямой путь, потом добавляйте только следующую действительно нужную возможность.

Еще одна полезная ветка — сравнение SDK и cURL. Если оба варианта падают одинаково, проблема обычно не в вашем приложении, а в access, model naming или organization context. Если cURL работает, а приложение нет, тогда вероятнее проблема в environment variables, request parsing или записи файла.

Есть и еще одно практическое правило, которое экономит много времени в команде: после первого успешного direct run сохраните prompt, model name, size, quality, точный cURL payload и получившийся файл как внутренний baseline. Когда через неделю кто-то добавит transparency, поменяет aspect ratio или начнет тестировать edits, у вас уже будет эталон, относительно которого легко понять, сломался ли account access, изменилась ли model availability, или проблема появилась только из-за нового параметра.

Полезно и разносить rollout по шагам. Сначала подтвердите, что один квадратный запрос стабильно проходит из SDK и из cURL. Затем отдельно проверьте decode-and-save, потому что часть сбоев находится не в API, а в локальной записи файла. И только после этого добавляйте output tuning, multi-image edits или Responses orchestration. Такой порядок обычно дает более чистые логи и делает обсуждение инцидентов внутри команды заметно короче.

Отдельно стоит договориться и о языке внутренних runbook notes. Если команда фиксирует: «этот пример проверен на Images API, на таком-то model name, с такими-то access prerequisites», то следующий разработчик не будет заново спорить с документацией и смешивать direct example с assistant route. Для этой темы такая дисциплина особенно полезна, потому что путаница почти всегда рождается не из сложного кода, а из смешения поверхностей API.

FAQ

Для нового примера лучше gpt-image-1.5 или gpt-image-1?

Для нового прямого примера выбирайте gpt-image-1.5. Официальная страница GPT Image 1.5 обозначает его как latest image generation model. gpt-image-1 по-прежнему полезен для migration и legacy-сравнений, но не как первый default.

Почему прямой пример возвращает base64, а не URL?

Потому что GPT image models по умолчанию возвращают base64 image data. Именно это и ломает многие старые ожидания, унаследованные от DALL·E-туториалов.

Нужен ли Responses для transparent PNG или image edits?

Нет. Прямой Images API уже поддерживает edits, input_fidelity, transparent background и output tuning через output_format и output_compression. Переходите на Responses ради orchestration, а не ради одного дополнительного параметра.

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

Для запроса openai image generation api example честный актуальный ответ уже, чем кажется по page one: начните с Images API, используйте gpt-image-1.5, держите первый запрос маленьким и квадратным и обязательно сохраняйте возвращенное base64-изображение на диск. Это по-прежнему самый быстрый рабочий путь на 23 марта 2026 года.

Переходите на Responses image_generation только тогда, когда вашему продукту действительно нужен image tool внутри большего workflow. Если держать эту границу четкой, большая часть текущей путаницы исчезает еще до первого оптимизационного шага.