通用异步图像生成

更新时间：2026-04-29

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

1. 接口概览

1.1 提交异步图片任务

POST /v1/images/tasks

支持：

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

1.2 查询异步图片任务

GET /v1/images/tasks/{task_id}

1.3 认证方式

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 可选值；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`

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

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

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 可选值中的值
`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`，可省略并由平台推断

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

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

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

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

成功响应：

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

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

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 查询任务

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 可选值
`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 参数约束​

NanoBanana capability options​

4.4 NanoBanana 系列能力差异​

4.5 计费​

5. gpt-image-2 参数​

5.1 文生图 JSON 请求​

5.2 图生图 JSON 请求​

5.3 图生图 multipart 请求​

5.4 参数约束​

GPT Image 2 quality options​

GPT Image 2 output format options​

GPT Image 2 size options​

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. 最小接入流程​