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

# Gemini Image 系列

> Google Gemini 图像生成 — Nano Banana 系列(原版 / Pro / 2),文生图 / 图像编辑 / 多图参考 / 局部重绘 / 搜索增强

Google Gemini 原生多模态图像系列,**三代 Nano Banana 演进 + 双档接入**:

* **Nano Banana 2(Gemini 3.1 Flash Image Preview)** — 轻量快速档,延迟低、成本省,**标准档独家支持 Google 文字 / 图片搜索增强**,支持 `0.5K`\~`4K` 分辨率,适合预览、批量、迭代
* **Nano Banana Pro(Gemini 3 Pro Image Preview)** — 旗舰档,4K 原生输出,专业级保真度,多步规划,内置质量分析
* **Nano Banana(Gemini 2.5 Flash Image Preview)** — 老一代主力,低延迟、高性价比,多图融合,角色一致性

每代提供两档接入:**标准档**(经济、性价比线)与 **官方直连档**(高 SLA、稳定性更高,价格更高)。两档同模型同能力,区别只在通道与计费。**推荐直接选用对应的 `-official` model id 切换通道**(语义清晰),也可在标准档上设 `official_fallback: true` 在运行时切换(官方直连档自身不支持该字段)。

按张计费;分辨率越高的档位单价越高。所有版本支持中英文 prompt。

## 定价

单位:美元 / 张。flat 档位不分分辨率;分档档位按 `resolution` 计价。

| 模型                                        | 0.5K / 1K         | 2K        | 4K         |
| ----------------------------------------- | ----------------- | --------- | ---------- |
| `gemini-3-pro-image-preview-official`     | `$0.1206`         | `$0.1206` | `$0.216`   |
| `gemini-3-pro-image-preview`              | `$0.045`          | `$0.045`  | `$0.05625` |
| `gemini-3.1-flash-image-preview-official` | `$0.0603`         | `$0.0909` | `$0.1359`  |
| `gemini-3.1-flash-image-preview`          | `$0.03375`        | `$0.045`  | `$0.0675`  |
| `gemini-2.5-flash-image-preview-official` | `$0.0351`(仅 1K)   | —         | —          |
| `gemini-2.5-flash-image-preview`          | `$0.014063`(仅 1K) | —         | —          |

<Note>
  3 Pro 的 `1K` 与 `2K` 同价(`$0.045` / `$0.1206`),仅 `4K` 加价。3.1 Flash 的 `0.5K` 与 `1K` 同价,`2K`、`4K` 逐档加价。2.5 Flash 仅支持 `1K`,为整条线最经济的档位。
</Note>

## 模式速查

所有 Gemini 图像模型只有两个 action:`generate`(文生图)与 `edit`(基于参考图改写 / 局部重绘)。多图融合、图生图都走 `edit` + `image_urls`。

| 模式                  | 触发字段                                            | 支持版本                |
| ------------------- | ----------------------------------------------- | ------------------- |
| **文生图**             | `action: "generate"`(默认)+ `prompt`              | 全部                  |
| **图像编辑 / 图生图**      | `action: "edit"` + `image_urls`                 | 全部                  |
| **多图参考融合**          | `action: "edit"` + `image_urls`(多张)             | 全部                  |
| **局部重绘(inpaint)**   | `action: "edit"` + `image_urls` + `mask_url`    | 全部                  |
| **搜索增强(grounding)** | `google_search: true`(可选 `google_image_search`) | **仅 3.1 Flash 标准档** |

## 调用示例

<CodeGroup>
  ```bash 文生图(最简,Nano Banana Pro) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview",
      "prompt": "极简主义工作室人像,柔和侧光,胶片质感,4K 锐利",
      "resolution": "4K",
      "aspect_ratio": "3:2"
    }'
  ```

  ```bash 多图融合(Nano Banana Pro) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview",
      "action": "edit",
      "prompt": "把第一张图的角色融入第二张图的场景,保持光影一致",
      "image_urls": [
        "https://cdn.example.com/character.jpg",
        "https://cdn.example.com/scene.jpg"
      ],
      "resolution": "4K",
      "aspect_ratio": "16:9"
    }'
  ```

  ```bash 局部重绘(inpaint,需 mask_url) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-2.5-flash-image-preview",
      "action": "edit",
      "prompt": "把背景换成海边日落,人物保持不变",
      "image_urls": ["https://cdn.example.com/portrait.jpg"],
      "mask_url": "https://cdn.example.com/mask.png",
      "aspect_ratio": "1:1"
    }'
  ```

  ```bash 搜索增强(3.1 Flash 标准档独家) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3.1-flash-image-preview",
      "prompt": "画一张本周登顶 App Store 的热门游戏的关键画面海报",
      "google_search": true,
      "google_image_search": true,
      "resolution": "2K",
      "aspect_ratio": "16:9"
    }'
  ```

  ```bash 官方直连档(高 SLA) theme={"system"}
  curl -X POST https://www.qingbo.dev/v1/tasks \
    -H "Authorization: Bearer $WAVE_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gemini-3-pro-image-preview-official",
      "prompt": "复杂排版海报,包含中英双语标语和密集小字,要求清晰可读",
      "resolution": "4K",
      "aspect_ratio": "2:3"
    }'
  ```
</CodeGroup>

<ResponseExample>
  ```json 提交成功 theme={"system"}
  {
    "task_id": "task-wave1775309821b950328499",
    "model": "gemini-3-pro-image-preview",
    "action": "generate",
    "status": "queued",
    "created_at": 1775309821040,
    "progress": 0
  }
  ```
</ResponseExample>

提交后用 [`GET /v1/tasks/{task_id}`](/cn/api-reference/task/status) 轮询状态,详见 [任务系统](/cn/docs/task-system)。

## 可用模型

| 模型 ID                                     | 系列                     | 说明                    |
| ----------------------------------------- | ---------------------- | --------------------- |
| `gemini-3-pro-image-preview-official`     | Nano Banana Pro · 官方直连 | 旗舰档,同模型直连,稳定性更高       |
| `gemini-3-pro-image-preview`              | Nano Banana Pro · 标准档  | 旗舰档,4K 原生,专业保真,多步规划   |
| `gemini-3.1-flash-image-preview-official` | Nano Banana 2 · 官方直连   | 快速档直连,支持 `0.5K`\~`4K` |
| `gemini-3.1-flash-image-preview`          | Nano Banana 2 · 标准档    | 快速档,Google 文字+图片搜索增强  |
| `gemini-2.5-flash-image-preview-official` | Nano Banana · 官方直连     | 老一代直连,高性价比            |
| `gemini-2.5-flash-image-preview`          | Nano Banana · 标准档      | 老一代主力,低延迟、多图融合        |

## 通用参数

<ParamField body="model" type="string" required>
  从 [可用模型](#可用模型) 列表中选一个
</ParamField>

<ParamField body="action" type="string" default="generate">
  操作类型,可选值:

  * `generate` — 文生图(默认)
  * `edit` — 基于参考图改写 / 图生图 / 多图融合 / 局部重绘(需配合 `image_urls`)
</ParamField>

<ParamField body="prompt" type="string" required>
  图像描述文本,支持中英文。Gemini 系列对自然语言指令理解力强,擅长接受多步骤、多约束 prompt
</ParamField>

<ParamField body="n" type="integer" default="1">
  生成数量(单次返回多张)
</ParamField>

<ParamField body="aspect_ratio" type="string" default="1:1">
  画面宽高比,全部 6 个模型支持以下 11 种取值:

  * `auto` — 自动选择(文生图默认 `1:1` 或 `16:9`;图生图跟随输入)
  * `1:1` — 正方形,头像 / 社媒
  * `2:3` / `3:2` — 竖 / 横版相机比
  * `3:4` / `4:3` — 竖 / 横版标准
  * `4:5` / `5:4` — 竖 / 横版社媒
  * `9:16` / `16:9` — 竖 / 横版宽屏
  * `21:9` — 超宽横幅
</ParamField>

<ParamField body="resolution" type="string" default="1K">
  输出分辨率,**取决于模型**:

  * 3 Pro:`1K` / `2K` / `4K`
  * 3.1 Flash:`0.5K` / `1K` / `2K` / `4K`
  * 2.5 Flash:仅 `1K`
</ParamField>

<ParamField body="image_urls" type="string[]">
  参考图片 URL 数组(仅 `edit` 使用)。图生图 / 局部重绘通常一张,多图融合可传多张
</ParamField>

<ParamField body="callback_url" type="string">
  Webhook 回调地址,任务终态时调用。详见 [回调机制](/cn/docs/sync-async#异步任务-webhook)
</ParamField>

<ParamField body="callback_events" type="string[]">
  回调事件过滤,如 `["completed", "failed"]`
</ParamField>

## 模型特定参数

<Tabs>
  <Tab title="3 Pro Official">
    **model id**:`gemini-3-pro-image-preview-official`

    **系列**:Nano Banana Pro · 官方直连档

    **支持 action**:`generate` / `edit`

    **resolution**:`1K` / `2K` / `4K`

    **aspect\_ratio**:11 种(含 `auto`)

    **核心特性**:与 3 Pro 标准档**完全同模型**,通道与稳定性更优,适合对 SLA 敏感的生产线。价格约为标准档的 2.7 倍(4K 约 3.8 倍)。

    <ParamField body="mask_url" type="string">
      局部重绘(inpaint)掩码图 URL,需配合 `image_urls`(仅一张),且掩码图需带 Alpha 通道
    </ParamField>
  </Tab>

  <Tab title="3 Pro">
    **model id**:`gemini-3-pro-image-preview`

    **系列**:Nano Banana Pro · 标准档

    **支持 action**:`generate` / `edit`

    **resolution**:`1K` / `2K` / `4K`

    **aspect\_ratio**:11 种(含 `auto`)

    **核心特性**:旗舰档,4K 原生输出,专业级保真度,多步规划与内置质量分析,擅长复杂构图与精细排版。

    <ParamField body="mask_url" type="string">
      局部重绘(inpaint)掩码图 URL,需配合 `image_urls`(仅一张),且掩码图需带 Alpha 通道
    </ParamField>

    <ParamField body="official_fallback" type="boolean" default="false">
      运行时切换到官方直连档,稳定性更高但价格更高。建议直接使用 `-official` 模型 id,语义更清晰
    </ParamField>
  </Tab>

  <Tab title="3.1 Flash Official">
    **model id**:`gemini-3.1-flash-image-preview-official`

    **系列**:Nano Banana 2 · 官方直连档

    **支持 action**:`generate` / `edit`

    **resolution**:`0.5K` / `1K` / `2K` / `4K`

    **aspect\_ratio**:11 种(含 `auto`)

    **核心特性**:与 3.1 Flash 标准档同模型,通道与 SLA 更优。**注意:官方直连档不支持 `google_search` / `google_image_search` 搜索增强**,如需搜索增强请用标准档 `gemini-3.1-flash-image-preview`。

    <ParamField body="mask_url" type="string">
      局部重绘(inpaint)掩码图 URL,需配合 `image_urls`(仅一张),且掩码图需带 Alpha 通道
    </ParamField>
  </Tab>

  <Tab title="3.1 Flash">
    **model id**:`gemini-3.1-flash-image-preview`

    **系列**:Nano Banana 2 · 标准档

    **支持 action**:`generate` / `edit`

    **resolution**:`0.5K` / `1K` / `2K` / `4K`

    **aspect\_ratio**:11 种(含 `auto`)

    **核心特性**:轻量快速档,延迟低、成本省,支持 `0.5K` 经济档到 `4K` 高清,适合预览、批量、迭代。**独家支持 Google 文字与图片搜索增强**,可基于实时网络信息出图。

    <ParamField body="google_search" type="boolean" default="false">
      启用 Google 文字搜索增强 — 模型可基于实时联网信息生成,适合需要真实世界信息的场景
    </ParamField>

    <ParamField body="google_image_search" type="boolean" default="false">
      启用 Google 图片搜索增强 — 在文字搜索基础上额外引用网络图片做视觉参考。**必须配合 `google_search: true` 使用**
    </ParamField>

    <ParamField body="official_fallback" type="boolean" default="false">
      运行时切换到官方直连档。建议直接使用 `-official` 模型 id(注意官方档不支持搜索增强)
    </ParamField>
  </Tab>

  <Tab title="2.5 Flash Official">
    **model id**:`gemini-2.5-flash-image-preview-official`

    **系列**:Nano Banana · 官方直连档

    **支持 action**:`generate` / `edit`

    **resolution**:仅 `1K`

    **aspect\_ratio**:11 种(含 `auto`)

    **核心特性**:老一代 Nano Banana 官方直连,通道稳定,适合在 2.5 Flash 上构建的存量管线。

    <ParamField body="mask_url" type="string">
      局部重绘(inpaint)掩码图 URL,需配合 `image_urls`(仅一张),且掩码图需带 Alpha 通道
    </ParamField>
  </Tab>

  <Tab title="2.5 Flash">
    **model id**:`gemini-2.5-flash-image-preview`

    **系列**:Nano Banana · 标准档

    **支持 action**:`generate` / `edit`

    **resolution**:仅 `1K`

    **aspect\_ratio**:11 种(含 `auto`)

    **核心特性**:老一代图像生成与编辑主力,低延迟、高性价比,多图融合与角色一致性表现稳定。当下最经济的 Gemini 图像档位。

    <ParamField body="mask_url" type="string">
      局部重绘(inpaint)掩码图 URL,需配合 `image_urls`(仅一张),且掩码图需带 Alpha 通道
    </ParamField>

    <ParamField body="official_fallback" type="boolean" default="false">
      运行时切换到官方直连档。建议直接使用 `-official` 模型 id
    </ParamField>
  </Tab>
</Tabs>

## 资源限制

| 项目     | 限制                                                                |
| ------ | ----------------------------------------------------------------- |
| 参考图片   | 多图融合可传多张;`edit` 局部重绘 / 图生图通常 1 张                                  |
| 掩码图    | `mask_url` 仅可一张,需带 Alpha 通道,与 `image_urls` 配合                     |
| 单张图片大小 | ≤ 30MB,支持 JPG / PNG / WEBP                                        |
| 输出分辨率  | 3 Pro 最高 4K / 3.1 Flash 最高 4K(最低 0.5K)/ 2.5 Flash 仅 1K            |
| 输出文件   | JPG,链接 24 小时有效                                                    |
| 搜索增强   | 仅 3.1 Flash 标准档;开启 `google_search` / `google_image_search` 可能略增延迟 |

## 相关文档

* [任务系统详解](/cn/docs/task-system) — 任务状态机 / 轮询节奏 / 异步推送
* [请求响应格式](/cn/docs/request-response) — 通用错误码 / Headers / 限流
* [认证](/cn/docs/authentication) — API Key 申请与使用