GPT-Image-2 API Руководство по модели

Краткий вывод

• Use POST /v1/images/generations with model=gpt-image-2.
• Supports prompt generation and reference_images URL inputs for guided generation.
• Reference images must be URLs, so local files must be uploaded first instead of passing base64 directly.
• The endpoint returns an async task id for later status polling.

Ключевые возможности

• Text to image：Submit standard prompt-driven image generation tasks through the unified API.
• Reference-guided generation：Pass image URLs through reference_images for style or subject guidance.
• Async task workflow：The endpoint returns a task id for queueing and polling pipelines.

Когда использовать

• When integrating a standard text-to-image workflow through the gateway.
• When references are needed for style continuation or subject guidance.
• When image generation must fit into async task orchestration.

Когда не использовать

• When a synchronous final image response is required.
• When your workflow depends on passing base64 references directly.

Особенности работы

• The endpoint returns a task object before the final image is ready.
• Poll queued, in_progress, completed, and failed states through the image task status API.
• Reference workflows require reference_images URLs, so local files must be uploaded first.
• size and resolution combinations must follow documented limits.

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

{
  "model": "gpt-image-2",
  "prompt": "Minimal premium cosmetics ad image with soft studio lighting and clean background",
  "size": "1:1",
  "resolution": "1K",
  "response_format": "url"
}

Минимальный ответ

{
  "id": "task_img_xxxxxxxx",
  "object": "generation.task",
  "model": "gpt-image-2",
  "status": "queued",
  "progress": 0,
  "created_at": 1703884800,
  "metadata": {}
}

Ключевые параметры

Частые ошибки

FAQ

1. How do I call gpt-image-2?
   Call POST /v1/images/generations with model=gpt-image-2, prompt, and optional size, resolution, and reference_images.
2. Does gpt-image-2 support image-to-image?
   Yes. Pass reference_images URLs to guide output style or subject consistency.
3. Why can’t I pass base64 reference images directly?
   The current docs require reference_images to be URLs. Upload local files first and then pass the returned URLs.
4. How do I check status after the task id is returned?
   Poll the image task status endpoint until the task is completed, then read the output image fields.
5. Ошибка у модели изображений или видео: invalid apitype: -1
   Обычно это означает, что запрос отправлен не в тот endpoint. Модели изображений и видео обычно не используют chat endpoint. Вместо этого нужно отправлять HTTP-запрос на создание задачи по документации и затем опрашивать endpoint статуса задачи. Сначала проверьте фактический код запроса, URL и payload.
6. Задача на генерацию изображения или видео завершилась ошибкой, но списание произошло
   Сначала попросите у пользователя лог задачи или скриншот и проверьте, есть ли там статистика входных или выходных токенов. Если учет токенов есть, запрос, скорее всего, был отправлен через chat endpoint, а не через правильный media workflow. Модели изображений и видео обычно работают как асинхронные HTTP task API: сначала отправляется задача, затем выполняется опрос по task id согласно документации.

Связанные API

• GPT-Image-2 Generation
• Upload Images
• Image Task Status