GPT-Image-2 API Model Guide

TL;DR

• 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.

Core Capabilities

• 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 to Use

• 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 Not to Use

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

Runtime Behavior

• 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.

Minimal Request

{
  "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"
}

Minimal Response

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

Key Parameters

Common Errors

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. 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.
6. 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

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