GPT-4o Image API Руководство по модели
Краткий вывод
- Supports prompt-based image generation for marketing, e-commerce, and creative workloads.
- Supports reference_images (up to 5) for image-to-image and style control.
- Supports mask_url for local inpainting and targeted edits.
Ключевые возможности
- High-quality text-to-image：Generate production-ready visuals through a unified API.
- Reference-guided consistency：Use reference_images to stabilize style and composition.
- Localized image edits：Use mask_url for precise partial edits and inpainting flows.
Когда использовать
- When generating product, ad, and campaign visuals quickly.
- When editing existing images with style consistency or localized changes.
Когда не использовать
- For long-form video generation or temporal shot control.
- For complex multi-turn reasoning chat workflows.
Особенности работы
- Uses the unified image generation endpoint with task-style responses and status polling.
- reference_images accepts up to 5 files with documented format and size limits.
- mask_url is optional for localized image edits.
Минимальный запрос
{
"model": "gpt-4o-image",
"prompt": "Premium product ad image, soft key light, minimal background, commercial photography style",
"size": "1:1",
"n": 1
}
Минимальный ответ
{
"id": "task_img_xxxxxxxx",
"object": "generation.task",
"model": "gpt-4o-image",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}
Ключевые параметры
| Параметр | Тип | Обяз. | По умолчанию | Диапазон | Описание |
|---|
| model | string | Да | gpt-4o-image | - | Exact model identifier from ToAPIs. |
| prompt | string | Да | - | - | Primary image instruction prompt. |
| size | string | Нет | 1:1 | 1:1 | 2:3 |
| n | integer | Нет | 1 | 1-4 | Number of images to generate per request. |
| reference_images | file[] | Нет | - | max 5 | Reference image array for image-to-image and style control. |
| mask_url | string | Нет | - | - | Mask image URL for local edits/inpainting. |
Частые ошибки
| HTTP | Code | Триггер | Исправление | Повтор |
|---|
| 400 | invalid_request_error | Missing fields, invalid types, or out-of-range values. | Validate model/prompt/size/n/reference_images/mask_url fields. | Retry after fixing payload. |
| 401 | authentication_error | Missing or invalid API key. | Verify Authorization header and key scope. | Retry after authentication is fixed. |
| 429 | rate_limit_exceeded | Request rate, concurrency, or current quota hits upstream rate limiting. | Apply exponential backoff first, then review request rate, concurrency, and quota usage. | Use 1s/2s/4s backoff with jitter; if it persists, reduce submission pressure. |
FAQ
- What is GPT-4o Image best for?
Best for high-frequency creative generation, brand visual expansion, and localized edits on existing assets.
- Why are image-to-image results unstable?
Check reference image quality/count and make preservation/style constraints explicit in the prompt.
- Ошибка у модели изображений или видео: invalid apitype: -1
Обычно это означает, что запрос отправлен не в тот endpoint. Модели изображений и видео обычно не используют chat endpoint. Вместо этого нужно отправлять HTTP-запрос на создание задачи по документации и затем опрашивать endpoint статуса задачи. Сначала проверьте фактический код запроса, URL и payload.
- Задача на генерацию изображения или видео завершилась ошибкой, но списание произошло
Сначала попросите у пользователя лог задачи или скриншот и проверьте, есть ли там статистика входных или выходных токенов. Если учет токенов есть, запрос, скорее всего, был отправлен через chat endpoint, а не через правильный media workflow. Модели изображений и видео обычно работают как асинхронные HTTP task API: сначала отправляется задача, затем выполняется опрос по task id согласно документации.
Связанные API
