# 通用异步图像生成

This file is the focused AI-readable context for one UniAll documentation page.

URL: https://docs.uniall.ai/zh-CN/models/image/async-image-generation
Locale: zh-CN
Markdown: https://docs.uniall.ai/ai/pages/zh-CN/models/image/async-image-generation.md
Description: 通用异步图像生成来源文档。

Agent guidance:
- Use this page when the user is asking about this specific route or model capability.
- Preserve endpoint paths, JSON keys, model IDs, and placeholder values exactly.
- Treat examples such as `sk-***`, `{BASE_URL}`, and `task_xxx` as safe placeholders, not real secrets.

## Page Markdown

更新时间：2026-04-29

本文说明如何使用图片异步任务接口调用 NanoBanana 系列模型和 `gpt-image-2`，包括请求方式、参数、响应、计费规则和两类模型的差异。

## 1. 接口概览

### 1.1 提交异步图片任务

```http
POST /v1/images/tasks
```

支持：

- 文生图：`task_type = text2image`
- 图生图：`task_type = image2image`

### 1.2 查询异步图片任务

```http
GET /v1/images/tasks/{task_id}
```

### 1.3 认证方式

```http
Authorization: Bearer sk-***
Content-Type: application/json
```

## 2. 可用模型

### 2.1 NanoBanana 系列

上游 Nano 系列模型包括：

| 模型名 | 说明 |
| --- | --- |
| `NanoBanana` | NanoBanana 基础模型 |
| `NanoBanana2-0.5K` | NanoBanana2，0.5K 档 |
| `NanoBanana2-1K` | NanoBanana2，1K 档 |
| `NanoBanana2-2K` | NanoBanana2，2K 档 |
| `NanoBanana2-4K` | NanoBanana2，4K 档 |
| `NanoBananaPro-1K` | NanoBanana Pro，1K 档 |
| `NanoBananaPro-2K` | NanoBanana Pro，2K 档 |
| `NanoBananaPro-4K` | NanoBanana Pro，4K 档 |
| `NanoBananaPro-8K` | NanoBanana Pro，8K 档 |

注意：最终用户是否能调用某个模型，取决于平台后台是否已在通道和计费中启用该模型。
### 2.2 gpt-image-2

| 模型名 | 说明 |
| --- | --- |
| `gpt-image-2` | 按 `size + quality + n` 参数矩阵计费的图片模型 |

## 3. 通用请求参数

这些字段适用于 NanoBanana 系列和 `gpt-image-2`。

| 参数 | 类型 | 必填 | 说明 |
| --- | --- | --- | --- |
| `model` | string | 是 | 模型名，例如 `NanoBanana2-0.5K`、`gpt-image-2` |
| `prompt` | string | 是 | 图片生成或编辑提示词 |
| `task_type` | string | 否 | `text2image` 或 `image2image`。不传时，后端会根据是否存在图片输入自动推断 |
| `image` | string / file | 图生图单图必填 | 单张参考图。JSON 中传图片 URL； |
| `images` | string[] | 图生图多图必填 | 多张参考图 URL，推荐多图统一使用这个字段 |
| `size` | string | 视模型而定 | 输出尺寸。`gpt-image-2` 必填，支持值见 [gpt-image-2 size 可选值](#gpt-image-2-size-options)；NanoBanana 系列优先使用 `aspect_ratio` 控制比例 |
| `aspect_ratio` | string | 部分模型可选 | `NanoBanana`、`NanoBananaPro-*`、`NanoBanana2-*` 支持，详见 [NanoBanana 系列能力差异](#nanobanana-capability-options)；`gpt-image-2` 不支持 |
| `quality` | string | 否 | 输出质量。`gpt-image-2` 支持值见 [gpt-image-2 quality 可选值](#gpt-image-2-quality-options)；NanoBanana 系列通常由模型档位决定 |
| `n` | integer | 否 | 生成数量。默认 `1`。`gpt-image-2` 允许 `1-8`；NanoBanana 不支持|
| `output_format` | string | 可选 | 控制输出图片类型。Nano 支持值见 [NanoBanana 系列能力差异](#nanobanana-capability-options)；`gpt-image-2` 支持值见 [gpt-image-2 output_format 可选值](#gpt-image-2-output-format-options) |


### 3.1 参考图传参口径

对外统一只推荐两个字段：

单图：

```json
{
  "image": "https://example.com/input.png"
}
```

多图：

```json
{
  "images": [
    "https://example.com/a.png",
    "https://example.com/b.png"
  ]
}
```

不要混用多个参考图字段。兼容旧字段仍会被解析并按顺序合并，混用可能导致重复参考图。新接入只使用 `image` 或 `images`。

任务类型推断规则：

- 没有图片输入：按 `text2image` 处理
- 有 `image` / `images` / multipart 图片文件：按 `image2image` 处理
- 显式传了 `task_type` 时，以显式值为准

## 4. NanoBanana 系列参数

NanoBanana 系列使用同一套异步图片任务请求结构。

### 4.1 文生图 JSON 请求

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "text2image",
  "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
  "aspect_ratio": "1:1",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 4.2 图生图 JSON 请求

```json
{
  "model": "NanoBanana2-0.5K",
  "task_type": "image2image",
  "prompt": "Turn the reference image into a clean product render",
  "image": "https://example.com/input.png",
  "aspect_ratio": "16:9",
  "output_format": "jpeg",
  "n": 1,
  "response_format": "url"
}
```

### 4.3 参数约束

| 参数 | NanoBanana 系列规则 |
| --- | --- |
| `model` | 传具体 Nano 模型名 |
| `prompt` | 必填 |
| `task_type` | `text2image` / `image2image`，可省略并由平台推断 |
| `aspect_ratio` | 推荐使用；控制输出比例。常见值包括 `1:1`、`16:9`、`9:16`、`4:3`、`3:4`，实际支持范围以上游模型为准 |
| `output_format` | 推荐使用；控制输出图片类型。`NanoBanana` 支持 `png` / `jpeg` / `webp`；`NanoBananaPro-*`、`NanoBanana2-*` 支持 `png` / `jpeg` |
| `size` | 不作为 NanoBanana 系列的主要控制参数；如传入，会按上游兼容能力处理 |
| `quality` | 不作为 NanoBanana 系列的平台计费维度；通常由模型档位决定 |
| `n` | 可选；默认 `1`。计费会按生成数量乘算，实际最大值以上游限制为准 |
| `response_format` | 推荐 `url` |
| 图片输入字段 | 单图用 `image`，多图用 `images`；multipart 上传文件时使用 `image` |

###### NanoBanana capability options

### 4.4 NanoBanana 系列能力差异

| 模型 | `aspect_ratio` | `output_format` |
| --- | --- | --- |
| `NanoBanana` | 支持 | 支持 `png` / `jpeg` / `webp` |
| `NanoBananaPro-*` | 支持 | 支持 `png` / `jpeg` |
| `NanoBanana2-*` | 支持 | 支持 `png` / `jpeg` |

### 4.5 计费

NanoBanana 系列按模型固定单价计费，再乘以生成数量 `n` 或实际上游返回的结果数量。

`aspect_ratio` 和 `output_format` 控制生成效果，不参与当前平台计费；不同 Nano 模型档位的基础单价由后台模型价格配置决定。

当前本地测试实例已启用 `NanoBanana2-0.5K`，具体消耗以平台后台价格配置和消费日志为准。

如果后台启用其他 NanoBanana 模型，需要分别配置对应模型价格。

## 5. gpt-image-2 参数

`gpt-image-2` 使用参数矩阵计费。`size` 是必填参数；`quality` 和 `n` 有默认值；`output_format` 可用于控制输出图片类型；不支持 `aspect_ratio`。

### 5.1 文生图 JSON 请求

```json
{
  "model": "gpt-image-2",
  "task_type": "text2image",
  "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
  "size": "1024x768",
  "quality": "low",
  "output_format": "webp",
  "n": 1,
  "response_format": "url"
}
```

### 5.2 图生图 JSON 请求

```json
{
  "model": "gpt-image-2",
  "task_type": "image2image",
  "prompt": "Keep the product shape, change the background to a bright studio scene",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "quality": "medium",
  "output_format": "png",
  "n": 1,
  "response_format": "url"
}
```

### 5.3 图生图 multipart 请求

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -F "model=gpt-image-2" \
  -F "task_type=image2image" \
  -F "prompt=Keep the subject, make it a clean studio product photo" \
  -F "size=1024x1024" \
  -F "quality=medium" \
  -F "output_format=png" \
  -F "n=1" \
  -F "response_format=url" \
  -F "image=@/path/to/input.png"
```

### 5.4 参数约束

| 参数 | 规则 |
| --- | --- |
| `size` | 必填，必须是 [gpt-image-2 size 可选值](#gpt-image-2-size-options) 中的值 |
| `aspect_ratio` | 不支持；请使用 `size` 控制输出尺寸和比例 |
| `quality` | 可选，默认 `medium`，支持值见 [gpt-image-2 quality 可选值](#gpt-image-2-quality-options) |
| `output_format` | 可选，支持值见 [gpt-image-2 output_format 可选值](#gpt-image-2-output-format-options) |
| `n` | 可选，默认 `1`，范围 `1-8` |
| `response_format` | 推荐 `url` |
| `task_type` | `text2image` / `image2image`，可省略并由平台推断 |

###### GPT Image 2 quality options

`quality` 支持值：

| 输入值 | 归一化后 |
| --- | --- |
| `low` | `low` |
| `medium` | `medium` |
| `high` | `high` |

###### GPT Image 2 output format options

`output_format` 支持值：

| 输入值 |
| --- |
| `png` |
| `jpeg` |
| `webp` |

###### GPT Image 2 size options

### 5.5 gpt-image-2 size 可选值

`gpt-image-2` 通过 `size` 控制输出尺寸和比例，不支持单独传 `aspect_ratio`。`quality` 可传 `low`、`medium`、`high`；`n` 会按生成数量计入最终消耗。

| Size | 比例 | 方向 | 备注档位 |
| --- | --- | --- | --- |
| `1024x768` | `4:3` | 横向 | `1K` |
| `768x1024` | `3:4` | 竖向 | `1K` |
| `1344x1024` | `4:3` | 横向 | `1K` |
| `1024x1344` | `3:4` | 竖向 | `1K` |
| `1280x1024` | `5:4` | 横向 | `1K` |
| `1024x1280` | `4:5` | 竖向 | `1K` |
| `1360x768` | `16:9` | 横向 | `1K` |
| `768x1360` | `9:16` | 竖向 | `1K` |
| `1536x864` | `16:9` | 横向 | `1K` |
| `864x1536` | `9:16` | 竖向 | `1K` |
| `1024x1024` | `1:1` | 正方形 | `1K` |
| `1536x1024` | `3:2` | 横向 | `1K` |
| `1024x1536` | `2:3` | 竖向 | `1K` |
| `2048x1024` | `2:1` | 横向 | `1K` |
| `1024x2048` | `1:2` | 竖向 | `1K` |
| `2016x864` | `21:9` | 横向 | `1K` |
| `864x2016` | `9:21` | 竖向 | `1K` |
| `1920x1080` | `16:9` | 横向 | `2K` |
| `1080x1920` | `9:16` | 竖向 | `2K` |
| `1536x1536` | `1:1` | 正方形 | `2K` |
| `2048x1360` | `3:2 近似` | 横向 | `2K` |
| `1360x2048` | `2:3 近似` | 竖向 | `2K` |
| `2048x1536` | `4:3` | 横向 | `2K` |
| `1536x2048` | `3:4` | 竖向 | `2K` |
| `2160x1440` | `3:2` | 横向 | `2K` |
| `1440x2160` | `2:3` | 竖向 | `2K` |
| `2048x1152` | `16:9` | 横向 | `2K` |
| `1152x2048` | `9:16` | 竖向 | `2K` |
| `2688x1344` | `2:1` | 横向 | `2K` |
| `1344x2688` | `1:2` | 竖向 | `2K` |
| `2688x1152` | `21:9` | 横向 | `2K` |
| `1152x2688` | `9:21` | 竖向 | `2K` |
| `2560x1440` | `16:9` | 横向 | `2K` |
| `1440x2560` | `9:16` | 竖向 | `2K` |
| `2048x2048` | `1:1` | 正方形 | `4K` |
| `2560x2048` | `5:4` | 横向 | `2K` |
| `2048x2560` | `4:5` | 竖向 | `2K` |
| `2880x2880` | `1:1` | 正方形 | `4K` |
| `3264x2448` | `4:3` | 横向 | `4K` |
| `2448x3264` | `3:4` | 竖向 | `4K` |
| `3504x2336` | `3:2` | 横向 | `4K` |
| `2336x3504` | `2:3` | 竖向 | `4K` |
| `3840x1920` | `2:1` | 横向 | `4K` |
| `1920x3840` | `1:2` | 竖向 | `4K` |
| `3840x1648` | `21:9 近似` | 横向 | `4K` |
| `1648x3840` | `9:21 近似` | 竖向 | `4K` |
| `3840x2160` | `16:9` | 横向 | `4K` |
| `2160x3840` | `9:16` | 竖向 | `4K` |

## 6. 提交响应

提交成功后返回任务对象。

```json
{
  "task_id": "task_xxx",
  "status": "succeeded",
  "progress": "100%",
  "result_url": "https://example.com/result.png",
  "metadata": {
    "task_type": "text2image",
    "result_count": 1
  },
  "error": null
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `task_id` | 平台任务 ID，用于后续查询 |
| `status` | `queued`、`processing`、`succeeded`、`failed` |
| `progress` | 任务进度，例如 `0%`、`50%`、`100%` |
| `result_url` | 第一张结果图 URL |
| `metadata.task_type` | 任务类型 |
| `metadata.result_count` | 结果数量 |
| `metadata.result_urls` | 多结果时返回 URL 数组 |
| `error` | 失败时包含错误信息，成功时为 `null` |

## 7. 查询响应

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

成功响应：

```json
{
  "code": "success",
  "message": "",
  "data": {
    "task_id": "task_xxx",
    "status": "succeeded",
    "progress": "100%",
    "result_url": "https://example.com/result.png",
    "metadata": {
      "task_type": "text2image",
      "result_count": 1
    },
    "error": null
  }
}
```

建议客户端轮询间隔为 `2-5` 秒。任务进入 `succeeded` 或 `failed` 后可停止轮询。

## 8. 完整 curl 示例

### 8.1 NanoBanana 文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "NanoBanana2-0.5K",
    "task_type": "text2image",
    "prompt": "A small red cube on a clean white desk, minimal product photo, soft daylight",
    "aspect_ratio": "1:1",
    "output_format": "png",
    "n": 1,
    "response_format": "url"
  }'
```

### 8.2 gpt-image-2 文生图

```bash
curl -X POST "{BASE_URL}/v1/images/tasks" \
  -H "Authorization: Bearer sk-***" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "task_type": "text2image",
    "prompt": "A small blue glass sphere on a clean white desk, minimal product photo, soft daylight",
    "size": "1024x768",
    "quality": "low",
    "output_format": "webp",
    "n": 1,
    "response_format": "url"
  }'
```

### 8.3 查询任务

```bash
curl "{BASE_URL}/v1/images/tasks/task_xxx" \
  -H "Authorization: Bearer sk-***"
```

## 9. NanoBanana 与 gpt-image-2 差异

| 对比项 | NanoBanana 系列 | `gpt-image-2` |
| --- | --- | --- |
| 模型列表 | 多个模型名区分基础版、Pro 和分辨率档位 | 单一模型名 |
| 当前本地已启用 | `NanoBanana2-0.5K` | `gpt-image-2` 已实测可用 |
| 计费方式 | 模型固定单价 * 生成数量 | `size + quality` 参数计费 * `n` |
| 比例控制 | 支持 `aspect_ratio`，例如 `1:1`,`2:3`,`3:2`,`3:4`,`4:3`,`4:5`,`5:4`,`9:16`,`16:9`,`21:9` | 不支持 `aspect_ratio`；使用 `size`，例如 `1024x768`、`1024x1024` |
| 输出格式控制 | `NanoBanana` 支持 `png` / `jpeg` / `webp`；`NanoBananaPro-*`、`NanoBanana2-*` 支持 `png` / `jpeg` | 支持 `png` / `jpeg` / `webp` |
| `size` | 不作为主要控制参数；模型档位和 `aspect_ratio` 更关键 | 必填，且必须命中 [gpt-image-2 size 可选值](#gpt-image-2-size-options) |
| `quality` | 不作为平台计费维度；通常由模型档位决定 | 可选，默认 `medium`，参与计费 |
| `n` | 可选，默认 `1`，最大值以上游限制为准 | 可选，默认 `1`，范围 `1-8` |
| `response_format` | 推荐 `url` | 推荐 `url` |
| 图生图 | 单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径 | 单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径 |


## 10. 最小接入流程

1. 使用 `POST /v1/images/tasks` 提交任务。
2. 保存返回的 `task_id`。
3. 使用 `GET /v1/images/tasks/{task_id}` 轮询任务。
4. 当 `status = succeeded` 时读取 `result_url`。