> ## 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-Hant/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-Hant/models/nano-banana/playground">
    直接在頁面裡發一次真實請求，看任務跑完。
  </Card>

  <Card title="非同步任務 API" icon="clock" href="/zh-Hant/api/async-tasks">
    信封、輪詢閉環、回撥與錯誤表。
  </Card>
</CardGroup>