GPT-4o Image API Model Guide
TL;DR
- 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.
Core Capabilities
- 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 to Use
- When generating product, ad, and campaign visuals quickly.
- When editing existing images with style consistency or localized changes.
When Not to Use
- For long-form video generation or temporal shot control.
- For complex multi-turn reasoning chat workflows.
Runtime Behavior
- 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.
Minimal Request
{
"model": "gpt-4o-image",
"prompt": "Premium product ad image, soft key light, minimal background, commercial photography style",
"size": "1:1",
"n": 1
}
Minimal Response
{
"id": "task_img_xxxxxxxx",
"object": "generation.task",
"model": "gpt-4o-image",
"status": "queued",
"progress": 0,
"created_at": 1703884800,
"metadata": {}
}
Key Parameters
| Parameter | Type | Required | Default | Range | Description |
|---|
| model | string | Yes | gpt-4o-image | - | Exact model identifier from ToAPIs. |
| prompt | string | Yes | - | - | Primary image instruction prompt. |
| size | string | No | 1:1 | 1:1 | 2:3 |
| n | integer | No | 1 | 1-4 | Number of images to generate per request. |
| reference_images | file[] | No | - | max 5 | Reference image array for image-to-image and style control. |
| mask_url | string | No | - | - | Mask image URL for local edits/inpainting. |
Common Errors
| HTTP | Code | Trigger | Fix Action | Retry Policy |
|---|
| 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.
- Image or video model error: invalid apitype: -1
This usually means the request was sent to the wrong endpoint. Image and video models typically do not use the chat endpoint. Instead, submit the documented HTTP task request and poll the task status endpoint for results. Check the actual request code, URL, and payload first.
- An image or video task failed, but the user was still charged
Ask the user for the task log or screenshot first and check whether input or output token usage appears. If token accounting shows up, the request was likely sent through a chat endpoint instead of the proper media workflow. Image and video models usually run as async HTTP task APIs: submit the task first, then poll by task id according to the relevant docs.
Related APIs
