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

# Nano Banana 系列

> WideRouter 上的 Google 图像生成模型：哪个 ID 走哪条链路、接受哪些参数，以及实测时延。

Nano Banana 是 Google 给这一代图像模型起的系列名。在 WideRouter 上，
**模型 ID 一律用官方名**——不提供平台自定义的别名，带 `-preview` 后缀的名字也不接受。

系列里的模型共用同一套请求形状，所以换模型就是改 `model` 一个词。

## 系列总览

|           | Nano Banana Pro      | Nano Banana 2            | Nano Banana              |
| --------- | -------------------- | ------------------------ | ------------------------ |
| **模型 ID** | `gemini-3-pro-image` | `gemini-3.1-flash-image` | `gemini-2.5-flash-image` |
| 异步任务 API  | 支持                   | 支持                       | 暂不可用                     |
| 同步接口      | 支持                   | 支持                       | 暂不可用                     |
| 分辨率档位     | `1K` `2K` `4K`       | `1K` `2K` `4K`           | —                        |
| 单次出图（`n`） | 1–4                  | 1–4                      | —                        |
| 参考图数量     | 最多 14                | 最多 14                    | —                        |
| 异步 1K 均值  | 约 29 秒               | 约 20 秒                   | —                        |
| 同步 1K 往返  | 约 17 秒               | 约 13 秒                   | —                        |

<Warning>
  `gemini-2.5-flash-image` 目前在两条链路上都不可路由：异步接口在提交时以
  `model_not_supported` 拒绝，同步接口返回价格未配置的错误。这里仍然列出它，
  是为了让你按官方 ID 查得到结果而不是一无所获——平台侧修好后即会开放。
</Warning>

默认选 **Nano Banana 2**：它在每个分辨率上都明显更快，参数又完全一样，
换过去不用改任何集成代码。只有当那点额外质量值得每张图多花十秒左右时，
才换成 **Nano Banana Pro**。

## 参数

所有参数都在 `input` 里。外层信封——`model`、`input`、`callback_url`——
见[异步任务 API](/zh/api/async-tasks)。

下面五个字段就是全集。`input` 里出现任何其他键都会被 `invalid_params` 拒掉，
所以拼错字段名会立刻报错，不会被静默忽略。

| 字段             | 类型        | 必填 | 取值范围           | 默认值    |
| -------------- | --------- | -- | -------------- | ------ |
| `prompt`       | string    | 是  | 1–32000 字节     | —      |
| `n`            | integer   | 否  | 1–4            | 1      |
| `aspect_ratio` | string    | 否  | 见[画幅比例](#画幅比例) | 模型自身默认 |
| `image_size`   | string    | 否  | `1K` `2K` `4K` | `1K`   |
| `images`       | string\[] | 否  | 最多 14 项        | 无      |

<Warning>
  `image_size` 区分大小写：`1K` 才对，`1k` 会被拒。异步接口没有 `512` 档位，
  也不接受 `1024x1024` 这种自由格式。
</Warning>

## 分辨率档位

`image_size` 缩放的是整幅画面，而不是把某一条边钉死，所以宽幅图在 `4K` 下
长边远超 4096 像素。实测，两个可用模型完全一致：

| `image_size` | `1:1`       | `21:9`      | 约合像素   |
| ------------ | ----------- | ----------- | ------ |
| `1K`         | 1024 × 1024 | 1584 × 672  | 100 万  |
| `2K`         | 2048 × 2048 | —           | 400 万  |
| `4K`         | 4096 × 4096 | 6336 × 2688 | 1700 万 |

文件体积随之变化：`1K` 约 0.4–0.7 MB，`2K` 约 2.4–3.0 MB，`4K` 约 7.5–8.2 MB。
产物一律是带 C2PA 内容凭证清单的 JPEG。

## 画幅比例

接受十个值。`gemini-3-pro-image` 在 `1K` 下的实测像素：

| 比例    | 像素          | 比例     | 像素         |
| ----- | ----------- | ------ | ---------- |
| `1:1` | 1024 × 1024 | `4:5`  | 928 × 1152 |
| `3:2` | 1264 × 848  | `5:4`  | 1152 × 928 |
| `2:3` | 848 × 1264  | `9:16` | 768 × 1376 |
| `4:3` | 1200 × 896  | `16:9` | 1376 × 768 |
| `3:4` | 896 × 1200  | `21:9` | 1584 × 672 |

每种比例都落在标称值的 1％ 以内。不传 `aspect_ratio` 时，纯文生图得到
1024 × 1024；传了 `images` 则跟随参考图的形状。

## 图生图与多图合成

在 `images` 里传参考图就是编辑或合成。每一项要么是 `https` URL，
要么是 base64 data URI——裸 base64 字符串会被拒，`http` 也会被拒。

```json theme={null}
{
  "model": "gemini-3-pro-image",
  "input": {
    "prompt": "place the leaf from the second image leaning against the mug from the first",
    "images": [
      "https://your-bucket.example/mug.jpg",
      "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ..."
    ]
  }
}
```

两种形式可以在同一次调用里混用，`aspect_ratio`、`image_size`、`n` 同样生效
——在 `4K` 下做编辑，产出确实是 4096 × 4096。

URL 是在**任务被受理之后**由服务端去取的，所以坏的参考图不会报 `400`，
而是让任务变成 `failed`。两个错误码告诉你是哪一层放弃的：

| 你传了什么                 | `error.code`        | 失败耗时   |
| --------------------- | ------------------- | ------ |
| 域名解析不了、404、或需要鉴权的 URL | `input_fetch_error` | 不到 1 秒 |
| 可达，但不是图片（HTML、JSON）   | `upstream_error`    | 约 4 秒  |

两者都发生在任何模型计算之前，所以失败很快，重试成本也低。

## 时延

异步数据来自 30 个任务、并发 12 的压测，同步数据来自单次调用。
这些数字用来判断量级，不是服务等级承诺。

|          | Nano Banana Pro | Nano Banana 2 |
| -------- | --------------- | ------------- |
| 异步提交调用   | 约 0.9 秒         | 约 0.9 秒       |
| 异步端到端，1K | 均值约 29 秒        | 均值约 20 秒      |
| 异步端到端，4K | 约 36–40 秒       | 约 41 秒        |
| 同步往返，1K  | 约 17 秒          | 约 13 秒        |

异步多花约 0.9 秒的往返，换来的是剩下 20–40 秒不用挂着连接。压测下排队
0–11 秒，已经计入上面的端到端数字。

## 同步接口形态

三种同步形态对两个可用模型都有效，且都把图片放在响应体里，不给 URL：

| 端点                                            | 图片在哪                                                                              |
| --------------------------------------------- | --------------------------------------------------------------------------------- |
| `POST /v1/images/generations`                 | `data[0].b64_json`；把 `response_format` 设为 `url` 则是 `data[0].url`。`n` 会被忽略，每次只回一张。 |
| `POST /v1/chat/completions`                   | 消息正文里的一段 Markdown 图片，src 是 data URI                                               |
| `POST /v1beta/models/{model}:generateContent` | `candidates[0].content.parts[]` 中的 `inlineData` 部分                                |

<Warning>
  在 Gemini 原生形态下，绝对不要按下标取 `parts`。它是长度与顺序都没有保证的异构数组：
  文本部分可能排在前面，复杂编辑任务还会返回若干张中间草稿。正确做法是筛出所有带
  `inlineData` 的项并取**最后一个**，同时从响应里读 `mimeType`，不要靠扩展名猜。
</Warning>

## 下一步

<CardGroup cols={2}>
  <Card title="Playground" icon="play" href="/zh/models/nano-banana/playground">
    直接在页面里发一次真实请求，看任务跑完。
  </Card>

  <Card title="异步任务 API" icon="clock" href="/zh/api/async-tasks">
    信封、轮询闭环、回调与错误表。
  </Card>
</CardGroup>