GPT Image 2: Create an Async Image Generation Task

POST /kyyReactApiServer/v1/image2/images — Generate images with GPT Image 2 using quality tiers, flexible sizing, and up to 16 reference images.

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

model · 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.

prompt · 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".

quality · 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

ratio · 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

resolution · 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.

size · 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, 2160x3840

Size 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

image_urls · 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

id · 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.

object · string

The object type. Always image.

created · integer

Unix timestamp indicating when the task was created.

model · string

The model name used for this task.

status · string

The initial task status immediately after creation.

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

error · string or null

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

---

Code Example

cURL

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

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.