> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qingbo.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Nano Banana 2.1

> Google Nano Banana 2.1 官方版：文生图与多图参考编辑，单次最多 4 张，按实际 token 用量结算

Nano Banana 2.1（`gemini-nano-banana-2.1`）是 Google 的图像模型，支持文生图和最多 14 张参考图的编辑，输出 `1k`、`2k`、`4k` 三档，每次请求最多返回 4 张，按实际 token 用量结算。它和 Nano Banana 2（`gemini-3.1-flash-image`，见[Nano Banana 官方版](/cn/api-reference/image/gemini/nano-banana)）是不同的模型：没有 `0.5k` 档，也不接受 `google_search` 与 `google_image_search`，从 Nano Banana 2 迁移时要去掉这几项。需要在提交前就确定单张费用时，用[Nano Banana 2.1 经济版](/cn/api-reference/image/gemini/nano-banana-2-1-rev)。

<Note>
  官方版与经济版不会自动互相切换：模型 ID 决定走哪条线路。
</Note>

## 快速开始

<CodeGroup>
  ```bash 文生图 theme={"system"}
  curl -X POST https://api.qingbo.ai/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: nb21-001" \
    -d '{
      "model": "gemini-nano-banana-2.1",
      "action": "generate",
      "prompt": "青瓷茶杯放在原木桌面上，窗边自然光，产品摄影",
      "aspect_ratio": "1:1",
      "resolution": "2k",
      "n": 1
    }'
  ```

  ```bash 一次多张 theme={"system"}
  curl -X POST https://api.qingbo.ai/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: nb21-batch-001" \
    -d '{
      "model": "gemini-nano-banana-2.1",
      "action": "generate",
      "prompt": "极简风格的咖啡馆标志，米白底色，线条干净",
      "aspect_ratio": "1:1",
      "resolution": "1k",
      "n": 4
    }'
  ```

  ```bash 参考图编辑 theme={"system"}
  curl -X POST https://api.qingbo.ai/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: nb21-edit-001" \
    -d '{
      "model": "gemini-nano-banana-2.1",
      "action": "edit",
      "prompt": "保留主体，把背景换成清晨的竹林",
      "image_urls": ["https://cdn.example.com/source.png"],
      "aspect_ratio": "auto",
      "resolution": "1k"
    }'
  ```

  ```bash 多图参考 theme={"system"}
  curl -X POST https://api.qingbo.ai/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-nano-banana-2.1",
      "action": "edit",
      "prompt": "把第一张的人物放进第二张的场景，光线统一",
      "image_urls": [
        "https://cdn.example.com/person.png",
        "https://cdn.example.com/scene.png"
      ],
      "aspect_ratio": "16:9",
      "resolution": "4k"
    }'
  ```
</CodeGroup>

提交成功后返回 `task_id`。用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 查询结果，也可以用 [`Prefer: wait`](/cn/api-reference/task/submit#请求内等待prefer-wait) 在一次调用里等待，或配置 Webhook。

## 请求参数

<ParamField body="model" type="string" required>
  固定为 `gemini-nano-banana-2.1`。
</ParamField>

<ParamField body="action" type="string" default="generate">
  * `generate`：根据文字生成图片
  * `edit`：基于参考图改写；必须提供 `image_urls`

  图生图、多图参考融合都走 `edit`，区别只在 `image_urls` 传几张。
</ParamField>

<ParamField body="prompt" type="string" required>
  图片描述或编辑指令，中英文均可。
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片 URL 数组。`edit` 时必填，最多 14 张。参考图按图片输入 token 计费，见「计费」。
</ParamField>

<ParamField body="aspect_ratio" type="string" default="auto">
  画面比例，14 种固定比例加 `auto`：`auto`、`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9`、`1:4`、`4:1`、`1:8`、`8:1`。

  `1:4`、`4:1`、`1:8`、`8:1` 适合长条横幅与竖幅，`1k`、`2k`、`4k` 三档都可用。

  `auto` 表示由模型决定：文生图按提示词内容选，图生图跟随输入图的比例。不传时按 `auto` 处理。
</ParamField>

<ParamField body="resolution" type="string" default="1k">
  输出分辨率：`1k`、`2k` 或 `4k`。不支持 `0.5k`，传了会返回 `400`。
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成数量，`1`–`4`。每张图分别计输出图像 token，`n` 越大，单次费用越高。
</ParamField>

通用的 `callback_url`、`callback_events`、`Prefer: wait`、`Idempotency-Key` 和费用上限请求头见[提交任务](/cn/api-reference/task/submit)。

<Warning>
  Nano Banana 2.1 不支持 `mask_url`、`quality`、`seed`，也不接受 Nano Banana 2 的 `google_search` 与 `google_image_search`。以上之外的参数会返回 `400`，不计费。需要掩码局部重绘时用 [`gpt-image-2`](/cn/api-reference/image/gpt-image/gpt-image-2)。
</Warning>

## 限制

| 条件 | 限制 |
| - | - |
| 每次请求 | 每次请求最多 4 张图。 |
| `action: "edit"` | 编辑图片需要至少一张参考图 |
| 参考图张数 | 最多 14 张 |
| 分辨率 | `1k`、`2k`、`4k`，不支持 `0.5k` |

## 计费

按实际 token 用量结算，共四个计费维度：

| 维度 | 包含 | `price_config.image_usage_rates` 键 |
| - | - | - |
| 文本输入 | 提示词 | `text_input` |
| 参考图输入 | `image_urls` 里的每张图 | `image_input` |
| 输出文本 | 模型出图过程中生成的思考文本 | `text_output` |
| 输出图像 | 生成的每张图 | `image_output` |

参考图越多、分辨率越高、`n` 越大，单次费用越高。

<Note>
  单价见 `GET /v1/models` 返回的 `price_config`，或控制台「模型市场」。

  单次调用的实际花费见任务响应里的 `cost`：整数 quota，500,000 quota = 1 USD，不是美元。
</Note>

### 冻结与结算

提交任务时按预估用量冻结一笔额度，任务完成后按实际用量结算，差额退回；结算金额不超过冻结的额度。预估用量的算法是：

* **输出图像**：按 `resolution` 查表得到每张图的预计输出 token，再乘以 `n`
* **输出文本**：按模型的最大输出 token 数预留，每次请求预留一份
* **文本输入**：按提示词的字节数预留，不足 64 按 64 计
* **参考图**：按 768 像素分块，每块 258 token

输出文本按上限预留，所以冻结的额度通常明显高于最终结算金额，差额在任务完成时退回。各分辨率的预计输出 token 见 `GET /v1/models` 的 `price_config.image_usage_reservation`。

只有成功出图才计费。任务失败、取消，或没有返回可用图片时，全额退款。

## 响应

```json 任务完成 theme={"system"}
{
  "task_id": "task-wave1791564843b950000001",
  "model": "gemini-nano-banana-2.1",
  "action": "generate",
  "status": "completed",
  "progress": "100%",
  "created_at": 1791564843,
  "completed_at": 1791564885,
  "billing_status": "settled",
  "cost": 41873,
  "result": {
    "images": [
      {
        "expires_at": 1792169685,
        "url": ["https://cdn.example.com/result-1.jpg"]
      },
      {
        "expires_at": 1792169685,
        "url": ["https://cdn.example.com/result-2.jpg"]
      }
    ]
  },
  "urls": {
    "get": "https://api.qingbo.ai/v1/tasks/task-wave1791564843b950000001",
    "cancel": "https://api.qingbo.ai/v1/tasks/task-wave1791564843b950000001/cancel"
  }
}
```

上例是 `n: 2` 的结果。`result.images` 每张图一项，`url` 是数组，`expires_at` 是图片链接的过期时间戳。完整字段说明见[查询任务状态](/cn/api-reference/task/status)。

## 相关文档

* [Gemini 图像系列](/cn/api-reference/image/gemini/overview)
* [Nano Banana 2.1 经济版](/cn/api-reference/image/gemini/nano-banana-2-1-rev)
* [Nano Banana 官方版](/cn/api-reference/image/gemini/nano-banana)
* [提交任务](/cn/api-reference/task/submit)
* [查询任务状态](/cn/api-reference/task/status)
* [任务系统](/cn/docs/task-system)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.