​
Prefer asynchronous jobs

Use POST /v1/images/generations/jobs for new integrations. It returns a task ID immediately and lets the client poll until the image is ready.
Use the synchronous endpoint for short requests or legacy clients:
The multipart edit endpoint is retained for compatibility, but is not recommended for new integrations:

​
Text-to-image

gpt-image-2, gpt-image-2-2K, and gpt-image-2-4K support synchronous and asynchronous generation. The higher-resolution variants require dimensions that match the model limits and should normally use the asynchronous endpoint.

​
Reference images

Use public image URLs or Base64 input in the asynchronous JSON request:
The image field accepts one URL or an array. images is also accepted for compatible clients. Do not send image, image[], and images in the same request. For Base64 input, use a complete data URL when possible:
Reference URLs must remain publicly accessible while the task is running. Resize large images before submission. Base64 input is decoded and uploaded to temporary storage before the model request.

​
Polling

  1. Create the job and save its id.
  2. Poll GET /v1/images/generations/jobs/{job_id} every two to three seconds for the first 30 seconds.
  3. Slow polling to five to ten seconds for longer jobs.
  4. Stop only at succeeded or failed.
  5. Read data on success and error.message on failure.
Do not recreate a job after a temporary network failure. Keep the original task ID so the user can resume after a page refresh.

​
Size and quality

Use size for the requested dimensions and quality for the model quality tier. The 2K and 4K variants validate width, height, aspect ratio, and pixel count more strictly than the base model. Follow the model limits shown in the API response and keep the original error body when diagnosing a rejected request.