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

# Gemini Banana 图片生成节点

> 在 ComfyUI 中使用 Gemini Banana 进行文生图、图生图和多图融合

## 节点概述

<Note>
  **节点标识：** `artsmcp-gemini-banana`\
  **技术栈：** Gemini 3 Pro Image\
  **功能：** 调用 Gemini Banana API 进行文生图、图生图、多图融合与批量生成
</Note>

### 支持的能力

* ✅ **文生图**：仅输入提示词生成图片
* ✅ **图生图**：单图输入，基于参考图生成新图片
* ✅ **多图融合**：输入 2–4 张图片进行融合生成
* ✅ **分行提示词批量生成**：多行提示词，每行独立处理
* ✅ **并发请求**：一次发送多路请求，显著提升生成效率
* ✅ **匹配参考尺寸**：可选按照参考图片尺寸本地裁剪/缩放输出
* ✅ **URL / Base64 响应格式**：兼容 URL 和 Base64（含 Data URI）

***

## 参数说明

### 必填与核心参数

| 参数名称      | 类型      | 说明                  | 示例值                                                                                              |
| --------- | ------- | ------------------- | ------------------------------------------------------------------------------------------------ |
| `提示词`     | STRING  | 图片生成的文本描述（支持多行）     | `"星际穿越，黑洞，电影大片"`                                                                                 |
| `API密钥`   | STRING  | API 身份验证密钥          | `sk-xxx`                                                                                         |
| `API地址`   | STRING  | 图片生成接口地址            | `https://api.openai.com/v1/images/generations`                                                   |
| `模型`      | ENUM    | 选择 Gemini Banana 模型 | `gemini-3-pro-image-preview` / `gemini-3-pro-image-preview-2k` / `gemini-3-pro-image-preview-4k` |
| `宽高比`     | ENUM    | 图片宽高比               | `1:1 / 2:3 / 3:2 / 3:4 / 4:3 / 4:5 / 5:4 / 9:16 / 16:9 / 21:9`                                   |
| `响应格式`    | ENUM    | 返回格式                | `URL / Base64`                                                                                   |
| `超时秒数`    | INT     | 单次 API 请求超时时间       | `120`                                                                                            |
| `最大重试次数`  | INT     | 失败后最大重试次数           | `3`                                                                                              |
| `并发请求数`   | INT     | 一次生成的图片数量           | `1-10`                                                                                           |
| `启用分行提示词` | BOOLEAN | 是否按行拆分提示词           | `False/True`                                                                                     |
| `匹配参考尺寸`  | BOOLEAN | 是否将输出图片匹配参考图尺寸      | `False/True`                                                                                     |
| `详细日志`    | BOOLEAN | 是否输出调试信息            | `False/True`                                                                                     |
| `参考图片1-4` | IMAGE   | 可选输入图片              | 用于图生图/多图融合                                                                                       |

<Info>
  * **推荐设置**：调试参数时可以先将并发请求数设置为 1，启用分行提示词后再逐步提高并发。
  * **提示词** 支持中英文，可使用多行详细描述画面、风格、光线等要素。
</Info>

***

## 功能模式

1. **文生图**
   * 仅填写提示词，不连接输入图片端口；
   * 适合从零构图、概念探索、海报/封面创作。

2. **图生图**
   * 连接 1 张参考图片到 `参考图片1`；
   * 提示词描述需要怎样“改造”这张图，如风格转换、细节增强等。

3. **多图融合**
   * 连接 2–4 张图片到 `参考图片1-4`；
   * 提示词中说明各图的作用，例如“参考第一张人物、第二张背景”。

4. **批量生成（分行提示词）**
   * 在提示词中每行写一个独立描述；
   * 勾选“启用分行提示词”；
   * `并发请求数 = N` 时，**行数 × N = 总生成张数**。

***

## 宽高比与尺寸

<ParamField path="宽高比" type="string" default="1:1">
  输出图片的目标构图比例。

  **可选值：**

  * `1:1`、`2:3`、`3:2`
  * `3:4`、`4:3`
  * `4:5`、`5:4`
  * `9:16`、`16:9`、`21:9`
</ParamField>

<ParamField path="匹配参考尺寸" type="boolean" default="false">
  是否在本地对生成结果进行二次处理，使其与参考图尺寸一致。

  * **开启**：使用第一张参考图的尺寸，对输出图片做 **智能缩放 + 居中裁剪**；
  * **关闭**：只使用 API 的宽高比进行构图，输出尺寸由服务端决定。

  <Info>
    技术实现：使用 LANCZOS 重采样 + 居中裁剪（与 README 描述保持一致）。
  </Info>
</ParamField>

<ParamField path="响应格式" type="string" default="URL">
  控制 API 响应中图片数据的表达方式：

  * `URL`：返回图片的网络地址（推荐，下载简单）；
  * `Base64`：返回 base64 编码的图片数据（自动兼容 `data:image/...;base64,...` 形式）。
</ParamField>

***

## 性能与重试参数

<ParamField path="超时秒数" type="integer" default="120">
  单次 API 请求的超时时间（单位：秒）。

  * 建议范围：`30-600`；
  * 分辨率越高、并发越多时可适当增大。
</ParamField>

<ParamField path="最大重试次数" type="integer" default="3">
  当调用返回 5xx 或 429 等错误时的重试次数。

  * 范围：`0-10`；
  * `0` 表示不重试；
  * 建议：一般场景 2-3 次即可。
</ParamField>

<ParamField path="并发请求数" type="integer" default="1">
  单次执行时并发发送的请求数量，即一次最多生成的图片数量。

  * 范围：`1-10`；
  * 若启用分行提示词：**总图片数 = 行数 × 并发请求数**。
</ParamField>

<ParamField path="启用分行提示词" type="boolean" default="false">
  是否将提示词按行拆分为多个独立任务。

  * 关闭：整段提示词作为一个任务；
  * 开启：每一行提示词单独生成一组图片。
</ParamField>

<ParamField path="详细日志" type="boolean" default="false">
  控制是否输出详细调试日志。

  * 开启后会打印：请求 payload、响应数据、重试信息等；
  * 仅在调试或排查问题时建议开启。
</ParamField>

<Info>
  **重试机制（与 README 一致）：**

  * 遇到 503 / 429 等错误时自动重试；
  * 采用 2s → 4s → 8s 的指数退避；
  * 对除 429 以外的 4xx 客户端错误不会重试，以避免浪费额度。
</Info>

***

## 输出说明

<ResponseField name="images" type="tuple">
  生成的图片列表，最终会写入 ComfyUI 输出目录并以列表形式输出。

  **文件信息：**

  * 文件格式：通常为 `.png`；
  * 命名规则：`ComfyUI_[序号].png`；
  * 默认保存路径：`ComfyUI/output/`。

  **多图输出：**

  * 分行提示词开启时，每行至少生成 `并发请求数` 张图片；
  * 结果会按照提示词行和并发序号顺序排列。
</ResponseField>

***

## 使用示例

### 示例 1：单张文生图

<Steps>
  <Step title="配置基本参数">
    * 模型：`gemini-3-pro-image-preview-2k`
    * 宽高比：`16:9`
    * 响应格式：`URL`
  </Step>

  <Step title="输入提示词">
    ```
    星际穿越，黑洞，电影大片，超现实主义，
    高对比度光影，富有戏剧张力
    ```
  </Step>

  <Step title="执行生成">
    并发请求数设置为 `1`，生成一张图片并通过 SaveImage 保存。
  </Step>
</Steps>

### 示例 2：图生图（匹配参考尺寸）

<Steps>
  <Step title="连接参考图片">
    将一张图片节点连接到 `参考图片1`，例如分辨率为 `1600×2848`。
  </Step>

  <Step title="设置参数">
    * 提示词：`"将这张图片转换为油画风格"`
    * 匹配参考尺寸：`True`
    * 宽高比：任意（只影响构图，不影响最终尺寸）
  </Step>

  <Step title="运行节点">
    输出图片将会被本地处理为 `1600×2848`，方便后续继续拼接或替换。
  </Step>
</Steps>

### 示例 3：多图融合

<Steps>
  <Step title="连接两张图片">
    * 参考图片1：人物照片；
    * 参考图片2：科幻城市背景。
  </Step>

  <Step title="输入提示词">
    ```
    将第一张图片中的人物与第二张图片的背景融合，
    打造赛博朋克风格的场景，霓虹灯光，高饱和度。
    ```
  </Step>

  <Step title="生成图片">
    * 并发请求数：`2`
    * 启用分行提示词：`False`
  </Step>
</Steps>

### 示例 4：分行提示词 + 并发批量生成

<Steps>
  <Step title="准备原图">
    将一张基础图片连接到 `参考图片1`。
  </Step>

  <Step title="启用分行提示词">
    * 启用分行提示词：`True`
    * 并发请求数：`3`
  </Step>

  <Step title="配置多行提示词">
    ```
    将这张图片转换为水彩画风格
    将这张图片转换为油画风格
    将这张图片转换为赛博朋克风格
    ```
  </Step>

  <Step title="执行生成">
    共输出 `3 行 × 3 并发 = 9` 张图片，可连接 SaveImage 统一保存。
  </Step>
</Steps>

***

## 常见问题

<AccordionGroup>
  <Accordion title="Gemini Banana 与 Doubao Seedream 有什么区别？">
    | 特性       | Gemini Banana    | Doubao Seedream |
    | -------- | ---------------- | --------------- |
    | **核心能力** | 文生图/图生图/多图融合     | 文生图/图生图/多图融合/组图 |
    | **响应格式** | URL / Base64     | URL / b64\_json |
    | **尺寸控制** | 通过宽高比 + 本地匹配参考尺寸 | 通过宽度/高度精确控制     |

    **选择建议：**

    * 如果已经有稳定的 Gemini 兼容服务，或希望沿用 OpenAI 风格接口 → 使用 **Gemini Banana**；
    * 如果更偏向豆包原生模型、需要精确像素控制和组图功能 → 使用 **Seedream**。
  </Accordion>

  <Accordion title="分行提示词和并发如何配合？">
    * 未开启分行提示词：`并发请求数 = 本次生成图片数量`；
    * 开启分行提示词：每一行会独立并发执行，**总张数 = 行数 × 并发请求数**；
    * 建议先用较小的并发值验证提示词，再逐渐增大。
  </Accordion>

  <Accordion title="为什么会出现 429 或 503 错误？">
    这些通常表示 **请求频率过高或服务端暂时过载**：

    * 插件会自动进行指数退避重试；
    * 可适当降低并发数或减小图片尺寸；
    * 若频繁出现，可调大超时和最大重试次数，并检查 API 限速规则。
  </Accordion>

  <Accordion title="详细日志应该什么时候打开？">
    * 当结果异常、生成失败或需要确认 payload 是否正确时；
    * 正常使用时建议关闭，以减少控制台输出和轻微的性能开销。
  </Accordion>
</AccordionGroup>