通用异步图像生成

本页示例中的 {BASE_URL} 表示 https://api.uniall.ai。

更新时间：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`	图片生成与编辑模型

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` 必填，见尺寸说明；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 可选值
`background`	string	否	仅适用于 `gpt-image-2`；待上线。`auto`（模型根据提示词决定背景）、`opaque`（不透明背景）或 `transparent`（透明背景）。省略或传 `null` 时默认 `auto`。

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 控制图片格式。

背景参数待上线。background 放在请求体顶层。

auto：模型根据提示词决定背景；省略或传 null 时使用此默认值。
opaque：指定不透明背景。
transparent：指定透明背景；output_format 必须为 png 或 webp，未传时默认 png。

非法 background 值，或 transparent 与 jpeg 的组合，会在请求校验阶段返回 HTTP 400，不会开始生成。

5.1 文生图 JSON 请求

{
  "model": "gpt-image-2",
  "task_type": "text2image",
  "prompt": "An orange cat sticker, full subject visible, transparent background",
  "size": "1024x768",
  "quality": "low",
  "background": "transparent",
  "output_format": "webp",
  "n": 1,
  "response_format": "url"
}

5.2 图生图 JSON 请求

{
  "model": "gpt-image-2",
  "task_type": "image2image",
  "prompt": "Keep the product shape and remove the background to make it transparent",
  "image": "https://example.com/input.png",
  "size": "1024x1024",
  "quality": "medium",
  "background": "transparent",
  "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 product shape and remove the background to make it transparent" \
  -F "size=1024x1024" \
  -F "quality=medium" \
  -F "background=transparent" \
  -F "output_format=png" \
  -F "n=1" \
  -F "response_format=url" \
  -F "image=@/path/to/input.png"

5.4 参数约束

参数	规则
`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

gpt-image-2 使用 size 指定输出宽高，例如 1024x1024；无需传入 aspect_ratio。quality 控制质量，n 控制生成数量。

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. 请求示例

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": "An orange cat sticker, full subject visible, transparent background",
    "size": "1024x768",
    "quality": "low",
    "background": "transparent",
    "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` 已实测可用
比例控制	支持 `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` 更关键	必填，见尺寸说明
`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​

6. 响应示例​

7. 查询响应​

8. 请求示例​

8.1 NanoBanana 文生图​

8.2 gpt-image-2 文生图​

8.3 查询任务​

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

10. 最小接入流程​