GPT Image 2: Create an Async Image Generation Task

GPT Image 2 generates high-quality images from text prompts with flexible quality tiers (low, medium, high) and multiple resolution options. Two model variants are available: gpt-image-2 supports up to 4K resolution and 6 reference images; gpt-image-2-r supports up to 16 reference images at 1K resolution. Tasks are processed asynchronously — you’ll receive a task ID immediately and can poll for the result once generation is complete.

Base URL

https://zcbservice.aizfw.cn/kyyReactApiServer

Endpoint

POST /v1/image2/images

Authentication

Include your API key as a Bearer token in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Models

GPT Image 2 offers two variants with different billing models and capabilities.

Model	Billing	Max Resolution	Max Reference Images
`gpt-image-2`	By quality tier	4K	6
`gpt-image-2-r`	By resolution	1K	16

Request Parameters

string

required

The model to use for image generation.

gpt-image-2 — billed by quality tier; supports up to 4K resolution and 6 reference images.
gpt-image-2-r — billed by resolution; supports up to 1K resolution and 16 reference images.

string

required

A text description of the image you want to generate. Clear, descriptive prompts produce the best results. Example: "A serene mountain lake at sunset, photorealistic".

string

default:"low"

The quality tier for the generated image. Only applies to the gpt-image-2 model — this parameter is ignored for gpt-image-2-r.

Value	Description
`low`	Fast generation, suitable for drafts and previews (default)
`medium`	Balanced speed and quality, suitable for general use
`high`	Maximum quality, suitable for final output and detail-rich scenes

string

default:"1:1"

The aspect ratio of the generated image. Required when you pass resolution. If you pass size instead, this field is optional.Supported values: 1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 5:4, 4:5, 2:1, 1:2, 21:9, 9:21

string

default:"1k"

The output resolution. You must also pass ratio when using this parameter. If you provide both size and resolution, size takes priority.

Value	Supported Models	Notes
`1k`	`gpt-image-2`, `gpt-image-2-r`	Default
`2k`	`gpt-image-2` only	—
`4k`	`gpt-image-2` only	Supported ratios: `16:9`, `9:16`, `2:1`, `1:2`, `21:9`, `9:21` only

gpt-image-2-r supports 1K only. 4K is limited to 6 specific ratios because other combinations exceed the maximum total pixel count.

string

An exact pixel dimension for the generated image, expressed as {width}x{height}. When provided, size overrides both resolution and ratio.Common examples: 1024x1024, 1536x1024, 1024x1536, 2048x2048, 2048x1152, 3840x2160, 2160x3840Size rules:

Maximum edge length: ≤ 3840 px
Both edges must be multiples of 16 px
Long-edge : short-edge ratio must not exceed 3:1
Total pixels must be between 655,360 and 8,294,400

array

An array of reference image URLs used to guide the visual style of the generated image.

gpt-image-2: up to 6 reference images
gpt-image-2-r: up to 16 reference images

Reference images are optional but can significantly improve style consistency.

Response Fields

string

The unique task ID for this generation job. Pass this value to the Query Image Task endpoint (GET /v1/result/{id}) to check status and retrieve your image.

string

The object type. Always image.

integer

Unix timestamp indicating when the task was created.

string

The model name used for this task.

string

The initial task status immediately after creation.

Value	Meaning
`queued`	Task is waiting in the queue
`processing`	Task is actively being processed

string or null

An error message describing what went wrong. null on a successful create; only populated when status is failed.

Code Example

curl -X POST https://zcbservice.aizfw.cn/kyyReactApiServer/v1/image2/images \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A serene mountain lake at sunset, photorealistic",
    "quality": "high",
    "ratio": "16:9",
    "resolution": "2k"
  }'

import requests

url = "https://zcbservice.aizfw.cn/kyyReactApiServer/v1/image2/images"

payload = {
    "model": "gpt-image-2",
    "prompt": "A serene mountain lake at sunset, photorealistic",
    "quality": "high",
    "ratio": "16:9",
    "resolution": "2k"
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)
print(response.json())

Success Response

{
  "id": "image_fd35ee52-2a98-44a6-b930-29a88ce9b8fd",
  "object": "image",
  "created": 1774836724,
  "model": "gpt-image-2",
  "status": "queued",
  "error": null
}

Failure Response

{
  "id": "image_fd35ee52-2a98-44a6-b930-29a88ce9b8fd",
  "object": "image",
  "created": 1774836724,
  "model": "gpt-image-2",
  "status": "failed",
  "error": "Invalid request: resolution '4k' is not supported for ratio '4:3'"
}

Image generation is processed asynchronously. The create endpoint returns a task id immediately — use that ID with the Query Image Task endpoint (GET /v1/result/{id}) to check task status and retrieve your image URL when generation is complete.

Size vs. resolution: When using resolution, you must also pass ratio (defaults to 1:1 if omitted). If you pass size, it takes full priority and you do not need to provide resolution or ratio. Never pass conflicting values — if both size and resolution are present, size wins.

Polling interval: Check the task status every 2–5 seconds using the Query Image Task endpoint. Stop polling as soon as status is completed or failed.

Overview

Text APIs

Image APIs

Video APIs

Asset Management

GPT Image 2: Create an Async Image Generation Task

Base URL

Endpoint

Authentication

Models

Request Parameters

Response Fields

Code Example

Success Response

Failure Response

​Base URL

​Endpoint

​Authentication

​Models

​Request Parameters

​Response Fields

​Code Example

​Success Response

​Failure Response

Base URL

Endpoint

Authentication

Models

Request Parameters

Response Fields

Code Example

Success Response

Failure Response