异步图片生成接口用户文档

更新时间：2026-04-29

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

1. 接口概览

1.1 提交异步图片任务

支持：

文生图：task_type = text2image

图生图：task_type = image2image

1.2 查询异步图片任务

1.3 认证方式

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 可选值；NanoBanana 系列优先使用 `aspect_ratio` 控制比例
`aspect_ratio`	string	部分模型可选	`NanoBanana`、`NanoBananaPro-`、`NanoBanana2-` 支持，详见 NanoBanana 系列能力差异；`gpt-image-2` 不支持
`quality`	string	否	输出质量。`gpt-image-2` 支持值见 gpt-image-2 quality 可选值；NanoBanana 系列通常由模型档位决定
`n`	integer	否	生成数量。默认 `1`。`gpt-image-2` 允许 `1-8`；NanoBanana 不支持
`output_format`	string	可选	控制输出图片类型。Nano 支持值见 NanoBanana 系列能力差异；`gpt-image-2` 支持值见 gpt-image-2 output_format 可选值

3.1 参考图传参口径

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

单图：

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

多图：

{
  "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 请求

{
  "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 请求

{
  "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`

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 请求

{
  "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 请求

{
  "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 请求

5.4 参数约束

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

quality 支持值：

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

output_format 支持值：

输入值
`png`
`jpeg`
`webp`

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. 提交响应

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

{
  "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. 查询响应

成功响应：

{
  "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 文生图

8.2 gpt-image-2 文生图

8.3 查询任务

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 可选值
`quality`	不作为平台计费维度；通常由模型档位决定	可选，默认 `medium`，参与计费
`n`	可选，默认 `1`，最大值以上游限制为准	可选，默认 `1`，范围 `1-8`
`response_format`	推荐 `url`	推荐 `url`
图生图	单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径	单图用 `image`，多图用 `images`，传参考图即走图生图/编辑路径

10. 最小接入流程

使用 POST /v1/images/tasks 提交任务。

保存返回的 task_id。

使用 GET /v1/images/tasks/{task_id} 轮询任务。

当 status = succeeded 时读取 result_url。

异步图片生成接口用户文档

1. 接口概览#

1.1 提交异步图片任务#

1.2 查询异步图片任务#

1.3 认证方式#

2. 可用模型#

2.1 NanoBanana 系列#

2.2 gpt-image-2#

3. 通用请求参数#

3.1 参考图传参口径#

4. NanoBanana 系列参数#

4.1 文生图 JSON 请求#

4.2 图生图 JSON 请求#

4.3 参数约束#

4.4 NanoBanana 系列能力差异#

4.5 计费#

5. gpt-image-2 参数#

5.1 文生图 JSON 请求#

5.2 图生图 JSON 请求#

5.3 图生图 multipart 请求#

5.4 参数约束#

5.5 gpt-image-2 size 可选值#

6. 提交响应#

7. 查询响应#

8. 完整 curl 示例#

8.1 NanoBanana 文生图#

8.2 gpt-image-2 文生图#

8.3 查询任务#

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

10. 最小接入流程#