> ## 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.

# 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：

```text theme={null}
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）

```bash theme={null}
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` 指定分辨率）：

```bash theme={null}
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 上传）

```bash theme={null}
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"
```

多张参考图：

```bash theme={null}
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）

```bash theme={null}
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 提交响应

```json theme={null}
{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "object": "image_task",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "queued",
  "created_at": 1761552000
}
```

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

***

## 6. 查询任务

### 6.1 请求

```bash theme={null}
curl -X GET $BASE_URL/v1/images/task/task_01HXXXXXXXXXXXXXXX \
  -H "Authorization: Bearer $API_KEY"
```

### 6.2 成功响应

```json theme={null}
{
  "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 处理中响应

```json theme={null}
{
  "id": "task_01HXXXXXXXXXXXXXXX",
  "object": "image_task",
  "task_id": "task_01HXXXXXXXXXXXXXXX",
  "status": "processing",
  "progress": "10%",
  "created_at": 1761552000
}
```

### 6.4 失败响应

```json theme={null}
{
  "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` 下载图片