# Nano Banana 系列 API：模型选择、接口选择与响应结构

Source: https://ofox.io/zh/docs/develop/models/nano-banana

Google 的 Gemini 图像模型，共五款。推荐通过 **Gemini 原生接口**调用，可精确控制比例与分辨率；OpenAI 兼容接口同样可用，但仅支持部分参数。

## 常见任务

- [指定比例和分辨率](https://ofox.io/zh/docs/develop/models/nano-banana/text-to-image) — 横图、竖图、4K 大图，各模型支持的取值。
- [改图与多图融合](https://ofox.io/zh/docs/develop/models/nano-banana/image-edit) — 上传图片，按文字指令编辑。
- [报错排查](https://ofox.io/zh/docs/develop/models/nano-banana/errors) — 400 invalid argument、比例不对、没有返回图片、410。

## 模型选择

**要点**:常规场景推荐 Nano Banana 2；需要 4K 输出或复杂构图时选用 Pro；批量生成小尺寸图片时选用 2 Lite。

- **Nano Banana 2.1**(最新): 1K、2K、4K 三档; 支持 1:8 至 8:1 的比例；2K、4K 实测约 2 分钟 — gemini-nano-banana-2.1
- **Nano Banana 2**(日常首选): 512 至 4K 四档分辨率; 支持的比例最多，含 1:8、8:1 — gemini-3.1-flash-image
- **Nano Banana Pro**(画质优先): 1K、2K、4K 三档; 生成前先进行推理，耗时较长 — gemini-3-pro-image
- **Nano Banana 2 Lite**(速度优先): 仅支持 1K; 实测单张约 5 秒，输出 JPEG — gemini-3.1-flash-lite-image
- **Nano Banana**(上一代): 固定约 1K，不支持指定分辨率; 已有项目可继续使用 — gemini-2.5-flash-image

**模型 ID（调用时原样复制）**

- Nano Banana 2.1: `google/gemini-nano-banana-2.1` — 最新
- Nano Banana 2: `google/gemini-3.1-flash-image` — 日常首选
- Nano Banana Pro: `google/gemini-3-pro-image` — 4K、复杂构图
- Nano Banana 2 Lite: `google/gemini-3.1-flash-lite-image` — 仅支持 1K
- Nano Banana: `google/gemini-2.5-flash-image` — 上一代

实时价格请参阅模型页：[Nano Banana 2](https://ofox.io/zh/models/google/gemini-3.1-flash-image)、[Nano Banana Pro](https://ofox.io/zh/models/google/gemini-3-pro-image)。实际扣费以响应里的 `usageMetadata` 为准。

## 接口选择

**要点**:需要控制比例和分辨率时，请使用 Gemini 原生接口。

| | Gemini 原生接口（推荐） | OpenAI 兼容接口 |
|---|---|---|
| 地址 | `POST /gemini/v1beta/models/<模型 ID>:generateContent` | `POST /v1/images/generations`、`/v1/images/edits` |
| 比例 | `imageConfig.aspectRatio` | 顶层 `aspect_ratio` |
| 分辨率 | `imageConfig.imageSize`：512、1K、2K、4K | **不支持**，传 `image_size` 返回 400 |
| `size: "宽x高"` | 不适用 | 不支持，用 `aspect_ratio` 指定比例 |
| `n` 多张 | 不适用 | 不支持，每次请求生成一张 |
| 改图 | `parts` 里放 `inlineData` | `/v1/images/edits` 上传文件 |
| 参考图 `input_images` | 不适用 | 不支持，改图用 `/v1/images/edits` |
| 返回 | `candidates[0].content.parts[].inlineData.data` | `data[0].b64_json` |

## 耗时与超时

**要点**:客户端超时设为 300 秒以上。

接口为同步调用。实测 1K 约 5 至 20 秒，4K 约 30 秒；Nano Banana 2.1 的 2K、4K 约 2 分钟。高峰期耗时会更长。Pro 在生成图片前会先进行推理（响应中含 `thoughtsTokenCount`），耗时高于同分辨率的 Nano Banana 2。常见的 60 秒默认超时无法覆盖 4K 及高峰期请求；客户端断开后，请求仍会计费。

## 响应结构

```json filename="200 OK（原生接口，data 已截断）"
{
  "candidates": [{
    "content": {
      "parts": [{ "inlineData": { "mimeType": "image/png", "data": "iVBORw0KGgo…" } }],
      "role": "model"
    },
    "finishReason": "STOP"
  }],
  "modelVersion": "google/gemini-3-pro-image",
  "usageMetadata": {
    "promptTokenCount": 7,
    "candidatesTokenCount": 2000,
    "candidatesTokensDetails": [{ "modality": "IMAGE", "tokenCount": 2000 }],
    "thoughtsTokenCount": 211,
    "totalTokenCount": 2218
  }
}
```

- 图片位于 `parts` 中含 `inlineData` 的项，**不一定是第一项**，其前可能有文字内容。请遍历 `parts` 查找。
- `candidatesTokensDetails` 中 `IMAGE` 项的数量即输出图片的 token 数。实测 1K 为 1,120，Pro 的 4K 为 2,000。
- `thoughtsTokenCount` 仅在 Pro 的响应中出现，表示生成图片前的推理 token。

## 官方文档
官方文档描述的是直连 Google 时的行为；通过 OfoxAI 调用时，以本页实测结论为准。

- [Gemini API · 图像生成](https://ai.google.dev/gemini-api/docs/image-generation)
- [Gemini API · 图像生成的比例与分辨率](https://ai.google.dev/gemini-api/docs/image-generation#aspect_ratios_and_image_size)
- [OfoxAI · Gemini 原生协议 generateContent](https://ofox.io/zh/docs/api/gemini/generate-content)

## 常见问题

**Nano Banana Pro 怎么生成 4K 图片？**

使用 Gemini 原生接口，在 generationConfig.imageConfig 中传入 imageSize: "4K"，同时用 aspectRatio 指定比例。实测 16:9 的 4K 输出 5504x3072，约 16 MB，耗时约 33 秒。OpenAI 兼容接口不支持 imageSize，传 image_size 会返回 400。

**Nano Banana 2 支持哪些比例？**

常用 10 种：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 四种超宽或超长比例。不在列表里的比例返回 400 Request contains an invalid argument。

**Nano Banana Pro 支持 1:8 或 4:1 吗？**

不支持。1:4、4:1、1:8、8:1 这四种比例只有 Nano Banana 2.1、Nano Banana 2 和 Nano Banana 2 Lite 支持，需要超长或超宽图请使用这三款。

**imageSize 要写 4K 还是 4k？**

推荐写大写 1K、2K、4K，与 Google 官方一致。实测 OfoxAI 也接受小写。512 档不带 K，只有 Nano Banana 2 支持。

**用 OpenAI 兼容接口怎么指定 Nano Banana 的比例？**

使用顶层的 aspect_ratio，例如 "16:9"。该接口不支持分辨率参数，需要 2K、4K 请使用 Gemini 原生接口的 imageConfig.imageSize。

**Nano Banana 一次能生成多张图吗？**

不能，一次请求生成一张。如需多张，请并发发起多次请求，注意速率限制。

**Nano Banana 超时设置多少合适？**

建议 300 秒以上。实测 1K 约 5 至 20 秒，4K 约 30 秒，Nano Banana 2.1 的 2K、4K 约 2 分钟，高峰期耗时更长。Pro 在生成前会先进行推理，耗时高于 Nano Banana 2。