ComfyUI-Custom-Batchbox 是一个强大的 ComfyUI 自定义节点系统，支持动态参数面板、多 API 供应商、自动故障转移，以及完整的可视化配置管理。
- 选择不同模型后，节点参数自动更新
- 支持参数分组（基础/高级）
- 支持多种参数类型：字符串、数字、下拉选择、开关
- 同一模型可配置多个 API 供应商
- 支持优先级排序
- 自动故障转移（Failover）
| 节点 | 功能 |
|---|---|
| 🖼️ 图片生成 | 文生图、图生图 |
| 📝 文本生成 | AI 脚本、广告词 |
| 🎬 视频生成 | AI 视频创作 |
| 🎵 音频生成 | AI 音频合成 |
| 🔧 图片编辑 | 局部重绘、超分 |
| 🔍 图像处理 | 高斯模糊放大预处理、无缝大图超分显示 |
- 内置 API Manager 界面
- 无需编辑 YAML 文件
- 支持热更新
- 安全审计体系 (Security Audit)：内置 Bandit/GitLeaks 自动化扫描及自检流程，守护配置与源码安全。
- 请求重试机制（指数退避）
- 结构化异常处理防崩溃机制
- 可配置日志级别与掩码（如密钥尾号打印）
- RGBA 透明度保持及 WebP 智能转码
- 生成图片自动保存到指定目录
- 可自定义命名格式（模型名、时间戳、seed 等）
- 支持 PNG/JPG/WebP 或保持原格式
- 按日期自动创建子文件夹
- API Manager 内可视化配置
- 重启 ComfyUI 后预览图片不丢失
- 自动从保存的文件恢复预览
- 详见 docs/preview_persistence.md
- 拖拽调整模型显示顺序
- 节点下拉框按配置顺序显示
- 顺序保存在
api_config.yaml
- 可配置默认宽度 - 在 API Manager → 保存设置 Tab 中调整（300-1200px）
- 新建节点使用配置的默认宽度
- 切换模型后保持用户设置的宽度
- 保存/加载工作流后宽度正确恢复
- 详见 docs/node_width_retrospective.md
- OpenAI 兼容格式 - 标准
/v1/chat/completions端点 - Gemini 原生格式 - 支持
/v1beta/models/{model}:generateContent- 支持
responseModalities: ['Image']强制只返回图片 - 自动解析 Gemini 响应中的 base64 图片
- 支持
- 在 API Manager 端点高级设置中切换 API 格式
- 为端点配置自动 prompt 前缀（如
生成一张图片：） - 用户输入
哈哈哈→ 实际发送生成一张图片：哈哈哈 - 用于强制模型生成图片而非文本回复
- 在 API Manager 端点高级设置中配置
- 点击节点上的"▶ 开始生成"按钮
- 只执行该节点及其上游依赖，不执行工作流中其他分支
- 大幅加速开发调试流程
- 浏览器控制台显示执行节点数量
- 开启后，全局 Queue Prompt 会自动跳过 BatchBox 节点
- 节点仅通过自身的"开始生成"按钮触发执行
- 避免 ComfyUI 重启后误执行所有 API 调用
- 在 API Manager → 节点显示设置中开关（默认开启）
- 绕过 ComfyUI 队列，多个节点可同时生成
- 点击节点按钮后直接调用 AI API，不等待其他节点
- 生成的图片自动保存并在节点上显示
- 重启后图片恢复（保存在 workflow 中）
- 适合批量迭代、多模型对比等高并发场景
已生成图片的节点行为类似 Load Image：
- 开启"拦截全局 Queue Prompt"：节点不执行，但下游节点仍能接收图片
- 关闭"拦截全局 Queue Prompt"：参数未变时直接返回缓存图片，不调用 API
- 重启后恢复：图片持久化到 workflow 中
- 独立生成和 Queue Prompt 共享缓存状态
参数变化检测开关（API Manager → 节点显示设置）：
- 开启（默认）：修改参数后 Queue Prompt 触发重新生成
- 关闭：仅按钮点击触发生成
-
将本项目放入 ComfyUI
custom_nodes目录：ComfyUI/custom_nodes/ComfyUI-Custom-Batchbox/ -
安装依赖：
pip install pyyaml requests
-
重启 ComfyUI
- 在 ComfyUI 菜单中找到 Batchbox API Manager
- 配置供应商：
- 名称（如
bltcy_ai） - Base URL（如
https://api.bltcy.ai） - API Key
- 名称（如
- 配置模型：
- 选择类别（图片/文本/视频等）
- 设置参数 Schema
- 配置 API 端点
编辑 api_config.yaml：
# 1. 供应商配置
providers:
bltcy_ai:
base_url: "https://api.bltcy.ai"
api_key: "sk-xxxxxxxx"
# 2. 模型配置
models:
banana_pro:
display_name: "🍌 Banana Pro"
category: image
parameter_schema:
basic:
prompt: { type: string, default: "" }
style:
type: select
default: realistic
options:
- { value: realistic, label: 写实风格 }
- { value: anime, label: 动漫风格 }
api_endpoints:
- provider: bltcy_ai
priority: 1
modes:
text2img:
endpoint: "/v1/images/generations"
img2img:
endpoint: "/v1/images/edits"
# 3. 全局设置
settings:
default_timeout: 600
max_retries: 3
auto_failover: true方式一：右键快捷菜单（推荐）
- 在画布空白处右键，直接选择 BatchBox 节点
- 可在 API Manager → 节点显示设置 中开关此功能
方式二：节点浏览器
- 搜索
ComfyUI-Custom-Batchbox，选择对应类型的节点
从下拉菜单选择已配置的模型，参数面板会自动更新。
- prompt: 必填，提示词
- image: 可选，用于图生图
连接输出后执行工作流。
每个模型可配置两种端点：
| 端点 | 用途 | 触发条件 |
|---|---|---|
| text2img | 文生图 | 无图片输入 |
| img2img | 图生图 | 有图片输入 |
配置规则：
- 至少配置一个端点
- 如只配置一个，另一个自动使用相同端点
ComfyUI-Custom-Batchbox/
├── __init__.py # 入口、API 端点注册
├── nodes.py # 节点定义
├── config_manager.py # 配置管理器（含缓存、验证）
├── batchbox_logger.py # 日志与重试模块
├── errors.py # 结构化异常类
├── image_utils.py # 图片处理工具
├── api_config.yaml # 配置文件
├── adapters/ # API 适配器
│ ├── base.py
│ ├── generic.py # 通用适配器（层级配置 + 重试）
│ └── template_engine.py
├── web/ # 前端资源
│ ├── api_manager.js
│ ├── api_manager.css
│ ├── dynamic_params.js
│ └── dynamic_inputs.js
├── tests/ # 单元测试
└── docs/ # 文档
如果你是第一次使用 Batchbox，推荐阅读 新手使用指南，包含：
- 5 分钟快速上手教程
- 图文配置说明
- 常见问题解答
- 进阶技巧
A: 检查依赖是否安装：
pip install pyyaml requestsA: 确保：
- 配置了多个供应商
settings.auto_failover设为true- 各端点的供应商优先级正确设置
A: 点击输入框旁边的 👁 按钮可以显示/隐藏。