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

# 图片异步生成

> 使用 /v2/images/generations 创建按张计费的图片生成任务，并查询问高云结果图。

图片异步接口适合长耗时、按张计费的图片生成场景。它不是 OpenAI 同步图片接口的简单别名，而是平台任务制接口：创建任务后立即返回任务 ID，平台在后台处理生成和结果转存，再按成功返回的图片数结算。

<Info>
  OpenAI 兼容图片接口仍是 `/v1/images/generations`；图片异步接口是 `/v2/images/generations`。两者在模型、endpoint、计费和返回结构上是隔离的。
</Info>

## 适用场景

| 场景                  | 推荐接口                     |
| ------------------- | ------------------------ |
| 需要 OpenAI 兼容同步响应    | `/v1/images/generations` |
| 需要按张计费、任务状态、后台转存结果图 | `/v2/images/generations` |
| 需要一次生成多张图片          | 当前创建多个异步任务；不要传 `n`       |

## 创建任务

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v2/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2-async",
    "prompt": "一张极简风格的云端工作站海报，蓝白配色，科技感",
    "size": "1:1"
  }'
```

NanoBanana 系列模型可指定分辨率，分辨率不改变按张计费方式：

```bash theme={null}
curl -X POST "https://xxx.wengaocloud.com/v2/images/generations" \
  -H "Authorization: Bearer $AI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nanobanana2-image",
    "prompt": "A cinematic city skyline at sunset",
    "size": "16:9",
    "resolution": "2K",
    "urls": ["https://example.com/reference.png"]
  }'
```

### 请求字段

| 字段           | 类型        | 必填 | 说明                                                                    |
| ------------ | --------- | -- | --------------------------------------------------------------------- |
| `model`      | string    | 是  | 支持 `images_generations_async` endpoint 的图片异步模型，例如 `gpt-image-2-async` |
| `prompt`     | string    | 是  | 图片生成提示词                                                               |
| `size`       | string    | 否  | 输出比例或尺寸口径，以模型能力为准；常用比例类值例如 `1:1`、`16:9`                               |
| `resolution` | string    | 否  | NanoBanana 系列分辨率字段，可选 `1K`、`2K`、`4K`；不按分辨率拆分价格                        |
| `urls`       | string\[] | 否  | 参考图 URL 列表。当前默认最多 8 张，超出会返回 400                                       |

<Warning>
  当前实现会拒绝 `n` 字段，返回 `invalid_request_error`。如果业务需要多张图片，请创建多个任务；不要把多个任务塞进一个请求。
</Warning>

### 创建响应

```json theme={null}
{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "queued",
  "created_at": 1779860000
}
```

`status=queued` 表示任务已经创建并完成冻结，后续由平台异步处理生成和结果转存。

## 查询任务

```bash theme={null}
curl "https://xxx.wengaocloud.com/v2/images/generations/imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3" \
  -H "Authorization: Bearer $AI_API_KEY"
```

### 处理中响应

```json theme={null}
{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "running",
  "created_at": 1779860000,
  "completed_at": null
}
```

### 成功响应

```json theme={null}
{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "succeeded",
  "created_at": 1779860000,
  "completed_at": 1779860032,
  "result": {
    "images": [
      {
        "url": "https://cdn.wengaocloud.com/images/ai/example.png"
      }
    ]
  }
}
```

返回给用户的是问高云侧结果图 URL。结果存储、URL 有效期和清理策略以后端配置为准。

### 失败响应

```json theme={null}
{
  "id": "imgtask_7f8c2a1c9e4d4bb7b3b7b0d9f6a1c2e3",
  "object": "image.generation.task",
  "model": "gpt-image-2-async",
  "status": "failed",
  "created_at": 1779860000,
  "completed_at": 1779860032,
  "error": {
    "code": "image_generation_failed",
    "message": "图片生成失败"
  }
}
```

## 状态说明

| 状态          | 含义                                |
| ----------- | --------------------------------- |
| `queued`    | 本地任务已创建，等待 worker 处理              |
| `running`   | 平台正在处理图片生成任务                      |
| `succeeded` | 已成功转存结果图并完成结算                     |
| `failed`    | 生成失败、结果缺失、转存失败或其他异常，平台会按结算策略退款或复核 |
| `cancelled` | 任务已取消，当前阶段通常不由用户主动触发              |

## 计费与安全

* 创建任务前会检查模型可见性、API Key 白名单、模型能力、价格配置和余额。
* 创建成功后会冻结预计费用；成功后按实际成功存储并返回的图片数结算。
* 任务查询按 `task_id + 用户 + 域名 + API Key` 做归属校验，不能查询其他 Key 创建的任务。
* 结果图 URL 视为敏感数据，不应该出现在普通日志、账单导出或公开错误信息中。

<Tip>
  如果你想做前端轮询，建议 2-5 秒查一次任务状态；不要高频刷新。
</Tip>