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

# 图像异步生成 API

> 使用 `POST /v1/images/generations/async` 提交图像异步生成任务，并通过任务查询接口获取最终结果。

# 图像异步生成 API

`/v1/images/generations/async` 用于提交图像异步生成任务。请求体采用 JSON 格式；提交成功后保存返回的任务 ID，并通过 `GET /v1/images/generations/async/{taskId}` 查询进度和最终结果。

* 异步入口为 `POST /v1/images/generations/async`。
* 查询入口为 `GET /v1/images/generations/async/{taskId}`。
* 当前已验证可用模型包括 `gpt-image-2`、`gpt-image-2-pro`、`gpt-image-2-vip`、Doubao Seedream 系列和 Gemini 图像模型。
* 异步任务的 `image` 目前只接受公网 `http(s)` 图片 URL，不支持 Base64 或 `data:` URI。
* 成功提交后优先读取 `id`、`task_id` 或 `taskId` 作为后续查询 ID。
* `prompt` 建议控制在 `1` 到 `4000` 个字符。
* `n` 表示生成数量，常用范围为 `1` 到 `10`。

## 方法与路径

```http theme={null}
POST /v1/images/generations/async
```

## 请求示例

<RequestExample>
  ```bash 文生图 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2",
      "prompt": "一张现代 API 平台首页插图，白底，青蓝色块，干净留白",
      "n": 1,
      "size": "1536x1024",
      "quality": "auto",
      "response_format": "url"
    }'
  ```

  ```bash 高质量生成 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-pro",
      "prompt": "一张电影级科技城市全景海报，清晨雾气，纵深透视，细节丰富",
      "n": 1,
      "size": "3840x2160",
      "quality": "high",
      "response_format": "url"
    }'
  ```

  ```bash VIP 尺寸 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-vip",
      "prompt": "一张高端科技发布会主视觉，超宽画幅，冷暖对比光，细节丰富",
      "n": 1,
      "size": "3808x1632",
      "quality": "high"
    }'
  ```

  ```bash Doubao Seedream cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "doubao-seedream-4-0-250828",
      "prompt": "一张白底产品主图，干净布光，商业摄影风格",
      "n": 1,
      "size": "1024x1024",
      "quality": "auto",
      "response_format": "url"
    }'
  ```

  ```bash Gemini 图像模型 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview",
      "prompt": "一张极简 API 文档封面图，白色背景，清晰几何构图",
      "n": 1,
      "size": "1024x1024",
      "quality": "auto",
      "response_format": "url"
    }'
  ```

  ```bash 参考图生成 cURL theme={null}
  curl -X POST https://www.geeknow.top/v1/images/generations/async \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-image-2-pro",
      "prompt": "参考图片中的商品，生成一张白底电商主图，保持材质和颜色一致",
      "n": 1,
      "size": "1536x1024",
      "quality": "high",
      "image": [
        "https://example.com/input.png"
      ]
    }'
  ```

  ```python Python theme={null}
  import requests

  resp = requests.post(
      "https://www.geeknow.top/v1/images/generations/async",
      headers={
          "Authorization": "Bearer YOUR_API_KEY",
          "Content-Type": "application/json",
      },
      json={
          "model": "gpt-image-2-pro",
          "prompt": "一张电影级科技城市全景海报，清晨雾气，纵深透视，细节丰富",
          "n": 1,
          "size": "3840x2160",
          "quality": "high",
          "response_format": "url",
      },
      timeout=60,
  )

  print(resp.json())
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://www.geeknow.top/v1/images/generations/async", {
    method: "POST",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: "gpt-image-2-pro",
      prompt: "一张电影级科技城市全景海报，清晨雾气，纵深透视，细节丰富",
      n: 1,
      size: "3840x2160",
      quality: "high",
      response_format: "url",
    }),
  });

  console.log(await response.json());
  ```
</RequestExample>

## 响应示例

<ResponseExample>
  ```json 200 - 任务已提交 theme={null}
  {
    "id": "task_img_abc123",
    "task_id": "task_img_abc123",
    "object": "image.generation.task",
    "model": "gpt-image-2-vip",
    "status": "queued",
    "created_at": 1735689600
  }
  ```

  ```json 200 - 已完成 theme={null}
  {
    "created": 1735689600,
    "data": [
      {
        "url": "https://example.com/images/task_img_abc123.png",
        "revised_prompt": "一张电影级科技城市全景海报，清晨雾气，纵深透视，细节丰富"
      }
    ],
    "size": "3840x2160",
    "quality": "high",
    "background": "opaque",
    "output_format": "png",
    "usage": {
      "input_tokens": 15,
      "total_tokens": 211,
      "output_tokens": 196,
      "input_tokens_details": {
        "text_tokens": 15
      },
      "output_tokens_details": {
        "image_tokens": 196
      }
    }
  }
  ```

  ```json 400 theme={null}
  {
    "error": {
      "message": "prompt is required",
      "type": "invalid_request_error",
      "param": "prompt",
      "code": "invalid_request"
    }
  }
  ```
</ResponseExample>

## 认证

```http theme={null}
Authorization: Bearer YOUR_API_KEY
```

## Body

<ParamField body="model" type="string" required>
  模型名称。当前已验证可用值包括 `gpt-image-2`、`gpt-image-2-pro`、`gpt-image-2-vip`、`doubao-seedream-4-0-250828`、`doubao-seedream-4-5-251128`、`doubao-seedream-5-0-260128`、`gemini-3-pro-image-preview`、`gemini-2.5-flash-image-preview`、`gemini-3.1-flash-image-preview`、`gemini-3.1-flash-lite-image`。VIP 模型名请使用 `gpt-image-2-vip`，不要传 `gpt-image-vip`。
</ParamField>

<ParamField body="prompt" type="string" required>
  文本提示词，用于描述想要生成的图片。建议控制在 `1` 到 `4000` 个字符。
</ParamField>

<ParamField body="n" type="integer">
  生成数量。常用范围为 `1` 到 `10`；未传时默认为 `1`。
</ParamField>

<ParamField body="size" type="string">
  输出尺寸。常见值包括 `1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`2048x1152`、`3840x2160`、`2160x3840`、`1920x1080`、`1080x1920`。`gpt-image-2-vip` 使用独立尺寸约束，常见值还包括 `2304x1728`、`3264x2448`、`3504x2336`、`3808x1632`。
</ParamField>

<ParamField body="image" type="array<string>">
  可选参考图输入。数组成员当前只接受公网可访问的 `http(s)` 图片 URL。
</ParamField>

<ParamField body="quality" type="string">
  质量等级。常见值为 `low`、`medium`、`high`、`auto`，默认 `auto`。
</ParamField>

<ParamField body="response_format" type="string">
  返回格式。常见值为 `url`、`b64_json`。`gpt-image-2-vip` 不建议依赖该字段强制切换返回格式。
</ParamField>

## Response

<ResponseField name="id" type="string">
  异步任务 ID。后续可传入 `GET /v1/images/generations/async/{taskId}` 查询任务状态。
</ResponseField>

<ResponseField name="task_id" type="string">
  异步任务 ID 的兼容字段。部分响应会使用下划线命名。
</ResponseField>

<ResponseField name="taskId" type="string">
  异步任务 ID 的兼容字段。部分响应会使用驼峰命名。
</ResponseField>

<ResponseField name="object" type="string">
  任务对象类型，通常为 `image.generation.task`。
</ResponseField>

<ResponseField name="model" type="string">
  任务使用的图像模型，例如 `gpt-image-2`、`gpt-image-2-pro`、`gpt-image-2-vip`、`doubao-seedream-4-0-250828`、`gemini-3-pro-image-preview` 或 `gemini-3.1-flash-lite-image`。
</ResponseField>

<ResponseField name="status" type="string">
  任务状态。提交后通常为 `queued`，轮询中可能出现 `processing` / `in_progress`。
</ResponseField>

<ResponseField name="created_at" type="integer">
  任务创建时间戳。
</ResponseField>

<ResponseField name="created" type="integer">
  最终结果对象的生成时间戳。
</ResponseField>

<ResponseField name="size" type="string">
  最终结果对象的输出尺寸，例如 `1024x1024`、`1536x1024` 或 `3840x2160`。
</ResponseField>

<ResponseField name="quality" type="string">
  最终结果对象的质量等级，例如 `low`。
</ResponseField>

<ResponseField name="background" type="string">
  最终结果对象的背景信息，例如 `opaque`。
</ResponseField>

<ResponseField name="output_format" type="string">
  最终结果对象的图片格式，例如 `png`。
</ResponseField>

<ResponseField name="usage" type="object">
  最终结果对象里的 token 统计信息。
</ResponseField>

<ResponseField name="data[].url" type="string">
  最终结果对象中 `response_format = url` 时返回的图片 URL。
</ResponseField>

<ResponseField name="data[].b64_json" type="string">
  最终结果对象中 `response_format = b64_json` 时返回的图片 Base64 数据。
</ResponseField>

<ResponseField name="data[].revised_prompt" type="string">
  部分上游会改写提示词并返回在这个字段里。
</ResponseField>

## 与同步接口的区别

| 项目   | 同步生图                                                            | 异步生图                                     |
| ---- | --------------------------------------------------------------- | ---------------------------------------- |
| 路径   | `/v1/images/generations`                                        | `/v1/images/generations/async`           |
| 请求字段 | `model`、`prompt`、`n`、`size`、`image`、`quality`、`response_format` | 按目标模型填写；异步 `image` 目前只接受公网 `http(s)` URL |
| 返回结构 | `created` + `data[]`                                            | 先返回任务对象；任务完成后查询接口直接返回结果对象                |
| 适用场景 | 响应时间较短的生图请求                                                     | 高分辨率、参考图或耗时较长的生图请求                       |

## 使用建议

* 如果调用方需要等待图片直接返回，优先使用同步接口 `/v1/images/generations`。
* 如果任务耗时较长，或业务需要提交后异步处理，使用 `/v1/images/generations/async`。
* Gemini 图像模型走异步入口时使用 OpenAI Images 兼容 JSON，不使用 `/v1beta/models/{model}:generateContent` 的 Gemini 原生请求体。
* 提交成功后保存 `id`、`task_id` 或 `taskId`，并调用任务查询接口轮询最终结果。
* `gpt-image-2-pro` 的常见高分辨率尺寸包括 `2048x2048`、`3840x2160`、`2160x3840`。
* `gpt-image-2-vip` 的 `size` 必须满足：每条边是 `16px` 倍数，最长边不超过 `3840px`，长短边比例不超过 `3:1`，总像素数在 `655,360` 到 `8,294,400` 之间。
* 异步参考图请使用公网 `http(s)` URL，不能传 Base64 / data URI。

## 相关页面

* [图像异步任务查询](/api-reference/images/gpt-image-async/query)
* [gpt-image-2 生成图像 API](/api-reference/images/gpt-image-2/generation)
* [gpt-image-2-pro 生成图像 API](/api-reference/images/gpt-image-2-pro/generation)
* [gpt-image-2-vip 生成图像 API](/api-reference/images/gpt-image-2-vip/generation)
* [Doubao Seedream 生成图像 API](/api-reference/images/doubao-seedream/generation)
* [Gemini 图像生成 API](/api-reference/images/gemini-image/generation)
* [OpenAI Images 兼容图像生成](/api-reference/images/gpt-image-1/generation)
* [图像模型支持矩阵](/api-reference/images/model-matrix)