nano-banana 异步接口

1. 概述

nano-banana 是本平台提供的 AI 图片生成模型，支持两种生成模式：

模型名称	能力	说明
`google-nanobanana-pro`	文生图 / 图片编辑	预览版模型
`google-nano-banana-2`	文生图 / 图片编辑	正式版模型

两个模型均同时支持 文生图（Text-to-Image）和 图片编辑（Image Edit），调用形状完全一致。备注：由于不同的模型名称对应不同的渠道和价格，具体上线使用请咨询业务人员获取专属的模型名称。

生成任务为异步流程：提交任务 → 拿到 task_id → 轮询查询结果。

2. 接口地址

方法	路径	Content-Type	作用
POST	`/v1/images/task/generations`	`application/json`	提交文生图异步任务（无参考图）
POST	`/v1/images/task/edits`	`application/json` 或 `multipart/form-data`	提交图片编辑异步任务（有参考图）
GET	`/v1/images/task/{task_id}`	—	查询任务状态 / 获取图片 URL

环境地址：

环境	Base URL
测试环境	`http://116.62.234.39:3000`
生产环境	`https://api.tkhub.ai`

下文示例统一以 $BASE_URL 表示，实际调用请替换为对应环境地址。

3. 认证

所有请求均需携带 API Key：

Authorization: Bearer <YOUR_API_KEY>

4. 提交任务

4.1 公共请求参数

字段	类型	必填	适用接口	说明
`model`	string	是	generations / edits	模型名称，需由业务人员配置提供
`prompt`	string	是	generations / edits	文本提示词，描述期望的图像内容或编辑指令，支持中英文
`size`	string	可选	generations / edits	图片尺寸，分辨率简写，可选值：`1K` / `2K` / `4K`
`aspect_ratio`	string	可选	generations / edits	图像宽高比，可选值：`1:1` / `2:3` / `3:2` / `3:4` / `4:3` / `4:5` / `5:4` / `9:16` / `16:9` / `21:9`

参数搭配建议：

仅需控制比例：传 aspect_ratio；

仅需控制分辨率：传 size（推荐 1K / 2K / 4K）；

同时控制：两个参数一起传；

都不传：由模型按默认配置生成。

4.2 edits 接口的图片输入

POST /v1/images/task/edits 需要额外传入参考图，支持以下两种方式（二选一）： 方式 A：multipart/form-data（推荐）

字段	类型	必填	说明
`image`	file / file[]	是	参考图文件。支持单张上传，也支持同名 `image` 字段多值上传

方式 B：application/json

字段	类型	必填	说明
`image`	string	是	单张参考图，支持 `http(s)://` 外链、`data:<mime>;base64,<payload>` Data URI、或裸 base64 字符串

4.3 参考图素材要求

格式：JPEG / JPG / PNG / WEBP / GIF
大小：建议 ≤ 10MB / 张
数量：multipart 方式支持多张，建议 ≤ 5 张

5. 请求示例

5.1 文生图（generations，JSON）

curl -X POST $BASE_URL/v1/images/task/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-nano-banana-2",
    "prompt": "一只蓝色的小猫坐在樱花树下，阳光洒落，电影质感",
    "size": "1K",
    "aspect_ratio": "1:1"
  }'

等价的紧凑写法（仅用 size 指定分辨率）：

curl -X POST $BASE_URL/v1/images/task/generations \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-nano-banana-2",
    "prompt": "一只蓝色的小猫坐在樱花树下",
    "size": "2K"
  }'

5.2 图片编辑（edits，multipart 上传）

curl -X POST $BASE_URL/v1/images/task/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=google-nano-banana-2" \
  -F "prompt=把这只猫换成橘色，并在背景加入月亮" \
  -F "size=1K" \
  -F "aspect_ratio=1:1" \
  -F "image=@./cat.png"

多张参考图：

curl -X POST $BASE_URL/v1/images/task/edits \
  -H "Authorization: Bearer $API_KEY" \
  -F "model=google-nano-banana-2" \
  -F "prompt=将两张图的人物合并到同一张合影中" \
  -F "image=@./p1.png" \
  -F "image=@./p2.png"

5.3 图片编辑（edits，JSON + URL）

curl -X POST $BASE_URL/v1/images/task/edits \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "google-nano-banana-2",
    "prompt": "把图中的天空改成星空",
    "image": "https://example.com/source.png",
    "aspect_ratio": "16:9"
  }'

5.4 提交响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "object": "image_task",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "queued",
  "created_at": 1761552000
}

请保存 task_id，用于后续查询。

6. 查询任务

6.1 请求

curl -X GET $BASE_URL/v1/images/task/task_01HXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer $API_KEY"

6.2 成功响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "object": "image_task",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "completed",
  "progress": "100%",
  "created_at": 1761552000,
  "finished_at": 1761552045,
  "result": {
    "created": 1761552000,
    "data": [
      {
        "url": "https://cdn.example.com/images/xxx.png?Expires=..."
      }
    ]
  }
}

图片下载地址位于 result.data[].url，一次任务可能返回一张或多张图片
URL 带有过期时间，建议尽快下载或转存到自有存储

6.3 处理中响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "object": "image_task",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "processing",
  "progress": "10%",
  "created_at": 1761552000
}

6.4 失败响应

{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "object": "image_task",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "failed",
  "progress": "100%",
  "created_at": 1761552000,
  "finished_at": 1761552030,
  "fail_reason": "error description"
}

任务失败不计费。

7. 任务状态

status	说明	终态
`queued`	已提交，排队中	否
`processing`	正在生成	否
`completed`	生成完成，可从 `result.data[].url` 下载图片	是
`failed`	生成失败（见 `fail_reason` 字段）	是

建议轮询策略：

间隔 ≥ 3 秒（图片任务通常 10~60 秒内完成）
超时建议 ≥ 5 分钟
命中终态（completed / failed）后停止轮询

8. 错误码

HTTP	code	说明
400	`InvalidParameter`	请求参数错误（如 prompt 为空、image 字段缺失、图片格式不支持）
401	`Unauthorized`	API Key 无效或未提供
403	`Forbidden`	无权限调用该模型
429	`RateLimitExceeded`	触发频率限制
500	`InternalError`	服务内部错误
503	`ServiceUnavailable`	上游服务不可用，建议稍后重试

9. 计费说明

计费单位：按次（每个成功任务计费一次）
影响因素：model（模型版本）× size（尺寸）
任务失败不计费
具体价格请查看平台「模型价格」页面

10. 常见问题

Q1：文生图和图片编辑接口如何选择？ A：无参考图（纯文生图）使用 /v1/images/task/generations；有参考图（图片编辑 / 融合）使用 /v1/images/task/edits。 Q2：size 和 aspect_ratio 如何搭配？ A：两者互补：

仅需控制比例：只传 aspect_ratio；
仅需控制分辨率：只传 size；
同时控制：两个参数一起传；
都不传：由模型按默认配置生成。

Q3：edits 接口支持多张参考图吗？ A：

multipart/form-data：使用同名 image 字段多值上传（推荐），如 -F "image=@ref1.png" -F "image=@ref2.png"；
application/json：目前仅支持单张 image（URL / Data URI / base64）。

Q4：image 字段支持哪些格式？ A：

http:// / https:// 外链（平台会自行下载原图）；
data:<mime>;base64,<payload> Data URI；
裸 base64 字符串（无 data: 前缀）；
multipart 文件上传（JPEG / PNG / WEBP / GIF 等）。

Q5：图片下载链接什么时候过期？ A：链接通常有若干小时的有效期。建议在获取到 completed 状态后立即下载，或转存到自有存储。 Q6：prompt 支持哪些语言？ A：支持中英文，中文在场景描写上效果较佳。 Q7：能否取消正在进行的任务？ A：当前不支持取消，任务一旦提交将执行至完成或失败。 Q8：一次任务会返回几张图？ A：通常为 1 张；若模型返回多张，均会通过 result.data[] 完整透出。

11. 快速接入清单

获取 API Key
准备调用环境，确认可访问测试或生产环境 Base URL
选择接口：文生图 → /v1/images/task/generations；图片编辑 → /v1/images/task/edits
按需设置 size（1K / 2K / 4K）与 aspect_ratio
edits 场景准备参考图（multipart 文件 / URL / Data URI / base64）
提交任务，保存 task_id
按 3~10 秒间隔轮询查询 /v1/images/task/{task_id}
在 status = completed 时从 result.data[].url 下载图片

概览

标准接口

特殊接口

帮助中心

隐私条款

nano-banana 异步接口

1. 概述

2. 接口地址

3. 认证

4. 提交任务

4.1 公共请求参数

4.2 edits 接口的图片输入

4.3 参考图素材要求

5. 请求示例

5.1 文生图（generations，JSON）

5.2 图片编辑（edits，multipart 上传）

5.3 图片编辑（edits，JSON + URL）

5.4 提交响应

6. 查询任务

6.1 请求

6.2 成功响应

6.3 处理中响应

6.4 失败响应

7. 任务状态

8. 错误码

9. 计费说明

10. 常见问题

11. 快速接入清单

​1. 概述

​2. 接口地址

​3. 认证

​4. 提交任务

​4.1 公共请求参数

​4.2 edits 接口的图片输入

​4.3 参考图素材要求

​5. 请求示例

​5.1 文生图（generations，JSON）

​5.2 图片编辑（edits，multipart 上传）

​5.3 图片编辑（edits，JSON + URL）

​5.4 提交响应

​6. 查询任务

​6.1 请求

​6.2 成功响应

​6.3 处理中响应

​6.4 失败响应

​7. 任务状态

​8. 错误码

​9. 计费说明

​10. 常见问题

​11. 快速接入清单

1. 概述

2. 接口地址

3. 认证

4. 提交任务

4.1 公共请求参数

4.2 edits 接口的图片输入

4.3 参考图素材要求

5. 请求示例

5.1 文生图（generations，JSON）

5.2 图片编辑（edits，multipart 上传）

5.3 图片编辑（edits，JSON + URL）

5.4 提交响应

6. 查询任务

6.1 请求

6.2 成功响应

6.3 处理中响应

6.4 失败响应

7. 任务状态

8. 错误码

9. 计费说明

10. 常见问题

11. 快速接入清单