> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xingchaoyiqing.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<ParamField body="model" type="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.
</ParamField>

<ParamField body="prompt" type="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"`.
</ParamField>

<ParamField body="quality" type="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 |
</ParamField>

<ParamField body="ratio" type="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`
</ParamField>

<ParamField body="resolution" type="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.
</ParamField>

<ParamField body="size" type="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
</ParamField>

<ParamField body="image_urls" type="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.
</ParamField>

***

## Response Fields

<ResponseField name="id" type="string">
  The unique task ID for this generation job. Pass this value to the [Query Image Task](/api-reference/image/gpt-image2-query) endpoint (`GET /v1/result/{id}`) to check status and retrieve your image.
</ResponseField>

<ResponseField name="object" type="string">
  The object type. Always `image`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp indicating when the task was created.
</ResponseField>

<ResponseField name="model" type="string">
  The model name used for this task.
</ResponseField>

<ResponseField name="status" type="string">
  The initial task status immediately after creation.

  | Value        | Meaning                          |
  | ------------ | -------------------------------- |
  | `queued`     | Task is waiting in the queue     |
  | `processing` | Task is actively being processed |
</ResponseField>

<ResponseField name="error" type="string or null">
  An error message describing what went wrong. `null` on a successful create; only populated when `status` is `failed`.
</ResponseField>

***

## Code Example

<CodeGroup>
  ```bash cURL theme={null}
  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"
    }'
  ```

  ```python Python theme={null}
  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())
  ```
</CodeGroup>

### Success Response

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

### Failure Response

```json theme={null}
{
  "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'"
}
```

***

<Note>
  Image generation is processed **asynchronously**. The create endpoint returns a task `id` immediately — use that ID with the [Query Image Task](/api-reference/image/gpt-image2-query) endpoint (`GET /v1/result/{id}`) to check task status and retrieve your image URL when generation is complete.
</Note>

<Tip>
  **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.
</Tip>

<Tip>
  **Polling interval:** Check the task status every **2–5 seconds** using the [Query Image Task](/api-reference/image/gpt-image2-query) endpoint. Stop polling as soon as `status` is `completed` or `failed`.
</Tip>