Extensions/ComfyUI-Nanobanana
ComfyUI Extension

ComfyUI-Nanobanana

Configurable Gemini image generation and editing node with native Gemini REST and OpenAI-compatible API support.

By yvtouyvtou·Created about a month ago·Updated about a month ago· 0
yvtouyvtou/ComfyUI-Yvtou-Gemini
Nodes—
On cloudLocal install
Stars0
Updatedabout a month ago
Readme

ComfyUI-Nanobanana

一个可配置的 ComfyUI Gemini 图片生成/编辑自定义节点，支持 Gemini 原生 REST 协议和 OpenAI 兼容协议。

功能特性

  • 双协议支持：Gemini 原生协议 (gemini_native) 和 OpenAI 兼容协议 (openai_compatible)
  • 可自定义 API 基础地址、端点路径、认证方式
  • 支持通过 extra_body_json 添加服务商特定字段
  • 最多 14 张输入图片，支持文生图和图生图模式
  • 输出图片自动归一化为统一批次尺寸（居中裁剪填充，无黑边）
  • 响应内容脱敏：API 密钥、敏感 URL 参数、大段 base64 数据自动脱敏

安装

方式一：ComfyUI Manager（推荐）

待本包发布到 Comfy Registry 后，在 ComfyUI Manager 中搜索 ComfyUI-Nanobanana 或 yvtou-gemini 即可安装。

方式二：Git Clone

cd ComfyUI/custom_nodes
git clone https://github.com/yvtouyvtou/ComfyUI-Yvtou-Gemini.git

方式三：手动下载

  1. 下载 ZIP 并解压到 ComfyUI/custom_nodes/ 目录
  2. 确保文件夹名为 ComfyUI-Yvtou-Gemini

安装依赖：

cd ComfyUI
python -m pip install -r custom_nodes\ComfyUI-Yvtou-Gemini\requirements.txt

重启 ComfyUI 即可在节点列表的 api/Gemini 分类下找到 ComfyUI-Nanobanana 节点。

快速开始

使用 Gemini 官方原生 API

  1. 获取 API 密钥：Google AI Studio
  2. 在节点中设置：
    • protocol: gemini_native
    • base_url: https://generativelanguage.googleapis.com
    • auth_mode: x_goog_api_key
    • api_key: 留空，设置环境变量 YVTOU_GEMINI_API_KEY=YOUR_API_KEY
    • model: gemini-3.1-flash-image

使用自定义 Gemini 兼容网关

  1. 在节点中设置：
    • protocol: gemini_native
    • base_url: https://your-provider.example.com
    • api_key: 按服务商要求填写或设置环境变量
    • model: 参考服务商文档中的模型名称

如有需要，可通过 auth_mode 切换认证方式（query_key / bearer / x_goog_api_key），通过 endpoint_path 自定义端点路径。

使用 OpenAI 兼容协议

  1. 在节点中设置：
    • protocol: openai_compatible
    • base_url: https://your-provider.example.com
    • api_key: 设置环境变量 OPENAI_API_KEY=YOUR_API_KEY
    • openai_api_style: chat_completions 或 images_api

不同服务商支持的模型名称和字段不同，请参考对应服务商的文档配置 extra_body_json。

输入参数

| 参数 | 类型 | 默认值 | 说明 | |------|------|--------|------| | protocol | 下拉 | gemini_native | 协议选择：gemini_native 或 openai_compatible | | base_url | 字符串 | https://your-provider.example.com | API 基础地址 | | api_key | 字符串 | (空) | API 密钥，留空则从环境变量获取 | | model | 字符串 | gemini-3.1-flash-image | 模型名称 | | prompt | 多行文本 | (空) | 图片生成/编辑提示词 | | mode | 下拉 | auto | 模式：auto（有图则编辑）、text2img、img2img | | aspect_ratio | 下拉 | auto | 宽高比：1:1, 16:9, 9:16, 4:3, 3:4, 3:2, 2:3, 4:5, 5:4, 21:9, 1:4, 4:1, 1:8, 8:1 | | image_size | 下拉 | 2K | 图片尺寸：512, 1K, 2K, 4K | | openai_api_style | 下拉 | chat_completions | OpenAI 风格：chat_completions 或 images_api（仅 openai_compatible 时生效） | | auth_mode | 下拉 | auto | 认证方式：auto、query_key、bearer、x_goog_api_key | | timeout_seconds | 整数 | 600 | 请求超时（秒），范围 10-3600 | | seed | 整数 | 0 | 随机种子，0 表示不设置 | | endpoint_path | 字符串 | (空) | 自定义端点路径，支持完整 URL 或相对路径 | | response_format | 下拉 | auto | 响应格式（仅 images_api）：auto、b64_json、url | | extra_body_json | JSON | {} | 额外请求体字段，会深度合并到请求中 | | image1 ~ image14 | IMAGE | (空) | 输入图片（最多 14 张） |

输出

| 输出 | 类型 | 说明 | |------|------|------| | image | IMAGE | 生成的图片张量 | | response | STRING | 响应元数据和文本内容 | | image_url | STRING | 返回的第一个图片 URL（如有） | | raw_response | STRING | 格式化的原始响应（已脱敏） |

协议说明

Gemini 原生协议 (gemini_native)

  • 默认端点：/v1beta/models/{model}:generateContent
  • 默认认证（auth_mode: auto）：URL 查询参数 ?key=...，此方式兼容性最广，适用于大多数第三方网关
  • 推荐认证（auth_mode: x_goog_api_key）：API 密钥通过 x-goog-api-key 请求头传递，适用于 Google 官方端点 generativelanguage.googleapis.com，密钥不会出现在 URL 中
  • 注意：并非所有第三方网关都支持请求头认证模式，请以服务商文档为准
  • 请求格式：Gemini REST API 的 contents 结构
  • 响应解析：从 candidates[].content.parts[] 提取图片和文本

官方当前支持的图片模型示例（截至 2026-07）：gemini-3.1-flash-image、gemini-3-pro-image、gemini-2.5-flash-image。请以 Google 官方文档 为准。

OpenAI 兼容协议 (openai_compatible)

  • chat_completions：使用 /v1/chat/completions 端点
  • images_api：使用 /v1/images/generations（文生图）或 /v1/images/edits（图生图）
  • 默认认证：Authorization: Bearer 头

服务商特定的模型名称和响应字段格式请参考对应服务商的文档。

API 密钥与安全

密钥配置优先级

  1. 节点 api_key 输入框
  2. 环境变量 YVTOU_GEMINI_API_KEY
  3. 环境变量 GEMINI_API_KEY
  4. 环境变量 OPENAI_API_KEY

安全建议

  • 优先使用环境变量：节点输入框中的密钥会保存在工作流 JSON 文件中，存在泄露风险
  • 不要在代码、截图、日志或 Issue 中暴露真实 API 密钥
  • 如果密钥不慎泄露，请立即到服务商后台撤销并重新生成；仅删除文本不会使已泄露的密钥失效
  • 发现安全漏洞请通过 GitHub 私有安全通告（Security Advisory）报告，不要提交公开 Issue

图片输入/输出行为

  • 14 张输入：节点支持 image1 到 image14 共 14 个可选图片输入
  • image1 输出尺寸权威：若连接了 image1，输出图片将归一化到 image1 的分辨率
  • 居中裁剪填充：不同宽高比的图片等比例缩放后居中裁剪至目标尺寸，无黑边、无几何拉伸
  • 回退行为：若未连接 image1 且返回图片尺寸不同，以返回图片中最大的一张为基准归一化
  • 批次兼容：归一化确保 ComfyUI 生成合法的批次张量
  • 归一化信息会显示在 response 输出中

高级用法

endpoint_path

  • 留空使用默认端点
  • 填写相对路径（如 /custom/path）会拼接到 base_url
  • 填写完整 URL（如 https://other.example.com/api）会完全替换端点

extra_body_json

可以添加、覆盖或删除请求体中的字段：

  • 合并：{"generationConfig": {"temperature": 0.5}}
  • 删除：{"generationConfig": {"imageConfig": null}}

OpenAI Images API 与图片尺寸

在 images_api 模式下，仅 aspect_ratio=1:1 且 image_size=1K 时自动映射为 1024x1024。其他组合请通过 extra_body_json 传入服务商特定的 size、aspect_ratio、image_size 或 image_config 参数，例如：

{"size": "1792x1024", "quality": "hd"}

故障排查

| 错误 | 可能原因 | 解决方法 | |------|----------|----------| | 400 Bad Request | 请求参数有误 | 检查模型名称、图片格式，尝试 extra_body_json 调整参数 | | 401/403 | 认证失败 | 检查 API 密钥是否正确，确认 auth_mode 设置 | | 404 Not Found | 端点不存在 | 检查 base_url 和 endpoint_path | | 超时 | 网络或服务端延迟 | 增加 timeout_seconds 值 | | 代理/连接错误 | 网络不通或代理配置问题 | 检查代理设置，确认目标地址可达 | | 成功但无图片 | 模型未返回图片 | 确认模型支持图片输出，检查 protocol 选择 | | 请求体过大 | 输入图片过多或分辨率过高 | 减少输入图片数量，降低图片分辨率 |

参考链接

许可证

本项目使用 MIT License。