Model Guide

GPT-4o Image

Model ID: gpt-4o-image

Vendor: OpenAIModalities: ChatPrice: Input $0.00/1M, Output $0.00/1MUpdated: 2026-05-02

GPT-4o Image is a GPT-4o image generation model on ToAPIs, supporting text-to-image and reference-guided editing with ToAPIs-aligned contracts.

Open in Playground Docs

Model Overview

Quick Answer

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.

GPT-4o Image Model Features

Core Section

Core capabilities and practical engineering value

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.

How to Use GPT-4o Image API

Set Authorization: Bearer <YOUR_API_KEY>.
Call GPT-4o image generation endpoint with model, prompt, and size.
Optionally pass reference_images and mask_url for guided edits.
Poll image task status and download result URLs.

When to Use

When generating product, ad, and campaign visuals quickly.
When editing existing images with style consistency or localized changes.

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.

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 \| 3:2	Output aspect ratio.
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

400 invalid_request_error

Trigger: Missing fields, invalid types, or out-of-range values.

Fix: Validate model/prompt/size/n/reference_images/mask_url fields.

Retry: Retry after fixing payload.

401 authentication_error

Trigger: Missing or invalid API key.

Fix: Verify Authorization header and key scope.

Retry: Retry after authentication is fixed.

429 rate_limit_exceeded

Trigger: Request rate, concurrency, or current quota hits upstream rate limiting.

Fix: Apply exponential backoff first, then review request rate, concurrency, and quota usage.

Retry: 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.

Mode Notes

Text to Image with GPT-4o Image

Generate images directly from text prompts.

Mode Parameters

modelpromptsizen

Best Scenarios

Product key visuals
Ad creatives
Concept art

Image-to-Image / Inpainting with GPT-4o Image

Use references and mask for style-guided edits or inpainting.