GPT Image 2 / 2.5 Integration

This guide explains how to generate images with the GPT Image 2 / 2.5 family through the OpenAI-compatible API, using either synchronous or asynchronous requests.

Supported models

• gpt-image-2-medium
• gpt-image-2.5-flare
• gpt-image-2.5-sunburst

Both the synchronous and asynchronous examples below use gpt-image-2.5-flare. To switch models, replace the request body's model value with its model ID from the list above. For gpt-image-2-medium, also remove the quality field: its default quality is medium. The endpoint paths, authentication, and asynchronous polling workflow are the same. Model availability depends on your API key's group and the selected site.

These three models share the same per-image pricing in the CN GPT Standard group. See Model Pricing for details; actual charges follow your API key's current group configuration.

Prerequisites

Get your API Base URL and API key from the console. The examples below assume that the Base URL does not end with /v1:

export API_BASE="https://<YOUR_API_BASE_URL>"
export API_KEY="<YOUR_API_KEY>"

All requests use Bearer Token authentication:

Authorization: Bearer <YOUR_API_KEY>

If the Base URL shown in the console already ends with /v1, do not add another /v1 to the request URL.

Size and quality controls

Both synchronous and asynchronous requests accept size in the JSON request body. Use quality to control quality for gpt-image-2.5-flare and gpt-image-2.5-sunburst; gpt-image-2-medium defaults to medium and does not require quality:

Parameter	Type	Values / format	Description
size	string	WIDTHxHEIGHT, for example 1024x1024	Requested dimensions in pixels, with a lowercase x between width and height.
quality	string	low, medium, high	For Flare / Sunburst, requests a low, medium, or high quality level. Omit this parameter for gpt-image-2-medium.

size is optional; set it explicitly when you need a specific size. For Flare / Sunburst, omitting quality uses the selected channel's default behavior; the Flare examples below use quality: "high". For gpt-image-2-medium, the default quality is medium, so omit quality.

gpt-image-2-medium request body

Use the following body for either synchronous or asynchronous generation. It includes size and omits quality:

{
  "model": "gpt-image-2-medium",
  "prompt": "An orange cat wearing a red scarf, sitting by a window and watching the snow",
  "size": "1024x1024",
  "n": 1
}

Standard size table

Prefer the standard size values below. Dimensions are in pixels, formatted as WIDTHxHEIGHT; copy the complete dimension string from a cell into the request body.

Aspect ratio	Orientation	1K	2K	4K
1:1	Square	1024x1024	2048x2048	2880x2880
5:4	Landscape	1120x896	2240x1792	3200x2560
4:3	Landscape	1152x864	2304x1728	3264x2448
3:2	Landscape	1248x832	2496x1664	3504x2336
16:9	Widescreen Landscape	1280x720	2560x1440	3840x2160
21:9	Ultrawide Landscape	1456x624	3024x1296	3696x1584
4:5	Portrait	896x1120	1792x2240	2560x3200
3:4	Portrait	864x1152	1728x2304	2448x3264
2:3	Portrait	832x1248	1664x2496	2336x3504
9:16	Widescreen Portrait	720x1280	1440x2560	2160x3840

1K, 2K, and 4K are product size tiers. The highest tier is named 4K; this does not mean every canvas has a 4096-pixel long edge. For example, a 4K square uses 2880x2880, while a 4K 16:9 landscape uses 3840x2160.

Send explicit dimensions, for example "size": "2560x1440", instead of a tier name such as 2K. Arbitrary non-standard dimensions may be rejected or automatically remapped. If exact pixels matter, check the downloaded image's actual width and height.

Quality and billing

For Flare / Sunburst, quality requests a quality level. gpt-image-2-medium defaults to medium and does not require this parameter. Quality does not set the image resolution in place of size. Actual visual quality and generation time depend on the model, channel, and image content. CN GPT Standard currently bills by image size tier. Within the same billing tier, low, medium, and high have the same per-image price. Other groups follow their current pricing.

Synchronous generation

The synchronous endpoint keeps the connection open until image generation completes or the request fails. Use it when your client can wait for a long-running response.

Endpoint

POST /v1/images/generations

Example request

curl "$API_BASE/v1/images/generations" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An orange cat wearing a red scarf, sitting by a window and watching the snow",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

Example success response

{
  "created": 1780000000,
  "data": [
    {
      "url": "https://<TEMPORARY_IMAGE_URL>"
    }
  ]
}

Read and download the image from data[0].url. Image generation can take some time. If your client, CDN, or reverse proxy is likely to time out on a long-lived connection, use the asynchronous workflow instead.

Asynchronous generation

The asynchronous endpoint creates a task and immediately returns a task ID while generation continues in the background. Your client then polls the task without keeping the original request open.

Step 1: Submit a task

POST /v1/images/generations/async

curl "$API_BASE/v1/images/generations/async" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2.5-flare",
    "prompt": "An orange cat wearing a red scarf, sitting by a window and watching the snow",
    "size": "1024x1024",
    "quality": "high",
    "n": 1
  }'

A successful submission returns HTTP 202 Accepted:

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "processing",
  "poll_url": "/v1/images/tasks/imgtask_example",
  "created_at": 1780000000,
  "expires_at": 1780086400
}

HTTP 202 only means that the task was accepted; it does not mean that the image is ready. Save the task_id and use the same API key that submitted the task when polling it.

Step 2: Poll the task

GET /v1/images/tasks/{task_id}

curl "$API_BASE/v1/images/tasks/imgtask_example" \
  -H "Authorization: Bearer $API_KEY"

Poll every 3–5 seconds. processing means generation is still running. Stop polling when the status becomes completed or failed. Polling a task does not incur another generation charge.

Example completed response

{
  "id": "imgtask_example",
  "task_id": "imgtask_example",
  "object": "image.generation.task",
  "status": "completed",
  "http_status": 200,
  "result": {
    "data": [
      {
        "url": "https://<SIGNED_IMAGE_URL_VALID_FOR_24_HOURS>"
      }
    ]
  },
  "created_at": 1780000000,
  "completed_at": 1780000060,
  "expires_at": 1780086460
}

After the task completes, read the image URL from result.data[0].url and download it immediately.

Asynchronous result retention

• Task records are retained for 24 hours: Task state is kept for 24 hours after its latest update and may no longer be available afterward.
• Image URLs are valid for 24 hours: The signed URL in a completed response is valid for 24 hours from creation. Polling again does not refresh or extend it.
• Images are deleted after 7 days: Asynchronous result images are automatically removed from platform storage 7 days after generation.
• Copy results promptly: Download the image before its URL expires and save it to your own object storage or file system. Do not treat the temporary URL as a permanent address.

Integration recommendations

• If a request may already have reached the server, do not blindly repeat the POST; doing so can create duplicate tasks and duplicate charges.
• Poll an asynchronous task with the same API key that submitted it.
• Set a reasonable overall task deadline in production and handle the failed status and error field correctly.
• After a successful download, store and serve the image through your own long-term URL.