Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tkhub.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
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/generationsapplication/json提交文生图异步任务（无参考图）
POST/v1/images/task/editsapplication/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 公共请求参数

字段类型必填适用接口说明
modelstring是generations / edits模型名称，需由业务人员配置提供
promptstring是generations / edits文本提示词，描述期望的图像内容或编辑指令，支持中英文
sizestring可选generations / edits图片尺寸，分辨率简写，可选值：1K / 2K / 4K
aspect_ratiostring可选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（推荐）
字段类型必填说明
imagefile / file[]是参考图文件。支持单张上传，也支持同名 image 字段多值上传
方式 B：application/json
字段类型必填说明
imagestring是单张参考图，支持 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. 错误码

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

​
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 下载图片