353 lines
9.7 KiB
Markdown
353 lines
9.7 KiB
Markdown
# PD ComfyUI API Nodes
|
||
|
||
ComfyUI 自定义节点集合，用于调用各种 AI 图像生成 API（GPT Image、Gemini Image、Flux Kontext）。
|
||
|
||
## 📦 节点列表
|
||
|
||
### ComfyUI AuthToken 版本（通过 ComfyUI 代理）
|
||
ComfyUI AuthToken 版本（通过 ComfyUI 代理）
|
||
- PD: GPT Image (comfyui_AuthToken)
|
||
- PD: Gemini Image (comfyui_AuthToken)
|
||
- PD: Flux Kontext (comfyui_AuthToken)
|
||
|
||
### 直接 API Key 版本直接调用官方comfyui的key
|
||
|
||
API Key 版本：
|
||
- 只保留 ComfyUI API Key 输入
|
||
- 参数和调用逻辑跟 ComfyUI 官方自带的 API 节点一样 - 只是在调用时可以手动填入 key
|
||
|
||
| 节点名称 | 文件 | 说明 |
|
||
|---------|------|------|
|
||
| **PD: GPT Image (apikey)** | `IMAGE_GPT_apikey.py` | OpenAI GPT Image 生成/编辑 |
|
||
| **PD: Gemini Image (apikey)** | `IMGE_GeminiNode_apikey.py` | Google Gemini 图像生成 |
|
||
| **PD: Gemini Pro Image (apikey)** | `IMGE_GeminiPro_apikey.py` | Google Gemini 3 Pro 高分辨率图像生成 |
|
||
| **PD: Flux Kontext (apikey)** | `IMGE_kontext_apikey.py` | Flux Kontext 图像编辑 |
|
||
|
||
---
|
||
|
||
## 🔑 两种版本的区别
|
||
|
||
### ComfyUI AuthToken 版本 (comfyui_AuthToken)
|
||
|
||
**认证方式**：使用 ComfyUI Auth Token，pandy自制油猴插件获取。
|
||
|
||
**认证头格式**：`Authorization: Bearer {auth_token}`
|
||
|
||
**使用示例**：
|
||
```
|
||
auth_token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzOGVhNmEw...
|
||
```
|
||
|
||
### API Key 版本 (apikey)
|
||
|
||
**认证方式**：使用 ComfyUI 官方 API Key
|
||
|
||
**认证头格式**：`X-API-KEY: {api_key}` （与 ComfyUI 官方 API 节点完全一致）
|
||
|
||
**使用示例**：
|
||
```
|
||
api_key: comfy_xxxxxxxxxxxxxxxxxxxxx
|
||
```
|
||
|
||
**特点**：
|
||
- 参数和调用逻辑跟 ComfyUI 官方自带的 API 节点一样
|
||
- 只是在调用时可以手动填入 key
|
||
- 直接使用官方账号的 key 申请下来填入使用
|
||
|
||
|
||
## 📖 节点详细说明
|
||
|
||
### 1. GPT Image 节点
|
||
|
||
**功能**：
|
||
- 文生图（Text-to-Image）
|
||
- 图片编辑（Image Editing）
|
||
- 图片修复（Inpainting with Mask）
|
||
|
||
**支持模型**：
|
||
|
||
**AuthToken 版本**：
|
||
- `gpt-image-1`：OpenAI GPT Image 1（推荐）
|
||
- `gpt-image-1.5`：OpenAI GPT Image 1.5（更高质量）
|
||
|
||
|
||
### 3. Gemini Pro Image 节点（Nano Banana Pro）
|
||
|
||
**功能**：
|
||
- 高分辨率图像生成（1K/2K/4K）
|
||
- 文生图（Text-to-Image）
|
||
- 图生图（Image-to-Image）
|
||
- 支持多张参考图片（最多14张）
|
||
- 同时输出图像和文本说明
|
||
|
||
**支持模型**：
|
||
- `gemini-3-pro-image-preview`：Gemini 3 Pro Image（最高质量）
|
||
|
||
**参数说明**：
|
||
- `prompt`：文本提示词，描述要生成的图像或编辑指令
|
||
- `model`：gemini-3-pro-image-preview
|
||
- `aspect_ratio`：宽高比
|
||
- auto：自动匹配输入图片比例，无图片时默认 16:9
|
||
- 1:1, 2:3, 3:2, 3:4, 4:3, 4:5, 5:4, 9:16, 16:9, 21:9
|
||
- `resolution`：目标输出分辨率
|
||
- 1K：标准分辨率
|
||
- 2K：使用原生 Gemini 放大器
|
||
- 4K：使用原生 Gemini 放大器（最高质量）
|
||
- `response_modalities`：输出模式
|
||
- IMAGE+TEXT：同时返回图像和文本说明
|
||
- IMAGE：仅返回图像
|
||
- `images`（可选）：参考图片（最多14张，使用 Batch Images 节点）
|
||
- `system_prompt`（可选）：系统提示词，默认使用官方优化的图像生成提示词
|
||
|
||
**输出**：
|
||
- `image`：生成的图像
|
||
- `text`：文本说明（包含模型的思考过程和描述）
|
||
|
||
**成本估算**：
|
||
- Gemini 3 Pro Image: 约 $0.12/张
|
||
- 基于 token 使用量：$2/1M input + $12/1M output text + $120/1M output image
|
||
|
||
**特殊说明（apikey 版本）**：
|
||
- 需要提供 `project_id`（Google Cloud 项目 ID）
|
||
- 需要提供 `location`（区域，默认 us-central1）
|
||
- 超时时间：180秒（因为高分辨率生成需要更长时间）
|
||
|
||
**使用建议**：
|
||
- 适合需要高质量、高分辨率图像的场景
|
||
- 2K/4K 分辨率会使用原生放大器，质量更好但成本更高
|
||
- IMAGE+TEXT 模式可以看到模型的思考过程，有助于理解生成结果
|
||
- 可以提供多张参考图片来引导生成风格
|
||
|
||
---
|
||
|
||
### 4. Flux Kontext 节点
|
||
|
||
**功能**：
|
||
- 图片编辑（Image Editing）
|
||
- 基于上下文的智能修改
|
||
|
||
**支持模型**：
|
||
- `flux-kontext-pro`：快速版本
|
||
- `flux-kontext-max`：高质量版本
|
||
|
||
**参数说明**：
|
||
- `prompt`：编辑指令
|
||
- `aspect_ratio`：宽高比
|
||
- `guidance`：提示词遵循度（0.1-99.0）
|
||
- `steps`：生成步数（1-150）
|
||
- `prompt_upsampling`：AI 增强提示词
|
||
- `input_image`（可选）：输入图片
|
||
|
||
**成本估算**：
|
||
- Kontext Pro: $0.05/张
|
||
- Kontext Max: $0.10/张
|
||
|
||
**特点**：
|
||
- 异步生成，需要轮询结果
|
||
- 最长等待时间：10 分钟
|
||
- 轮询间隔：2 秒
|
||
|
||
---
|
||
|
||
## 🚀 使用建议
|
||
|
||
### 选择 ComfyUI AuthToken 版本，如果你：
|
||
- ✅ 已经有 ComfyUI Auth Token
|
||
- ✅ 想要统一管理多个 AI 模型
|
||
- ✅ 喜欢通过 ComfyUI 生态系统
|
||
- ✅ 不想配置多个平台的 API Key
|
||
|
||
### 选择直接 API Key 版本，如果你：
|
||
- ✅ 已经有各个平台的 API Key
|
||
- ✅ 想要直接控制 API 调用
|
||
- ✅ 不想依赖 ComfyUI 代理服务
|
||
- ✅ 需要更灵活的配置（如 Gemini 的 project_id）
|
||
|
||
---
|
||
|
||
## 📝 使用示例
|
||
|
||
### 示例 1：使用 ComfyUI AuthToken 生成图片（GPT Image）
|
||
|
||
```
|
||
节点：PD: GPT Image (comfyui_AuthToken)
|
||
|
||
参数：
|
||
- auth_token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzOGVhNmEw...
|
||
- prompt: A futuristic city with flying cars at sunset
|
||
- model: gpt-image-1
|
||
- quality: medium
|
||
- background: auto
|
||
- size: 1024x1024
|
||
- n: 1
|
||
```
|
||
|
||
### 示例 2：使用直接 API Key 生成图片（DALL-E）
|
||
|
||
```
|
||
节点：PD: GPT Image (apikey)
|
||
|
||
参数：
|
||
- api_key: sk-proj-abc123...
|
||
- prompt: A futuristic city with flying cars at sunset
|
||
- model: dall-e-3
|
||
- quality: hd
|
||
- size: 1024x1792
|
||
```
|
||
|
||
### 示例 3：使用 Gemini 生成图片（apikey 版本）
|
||
|
||
```
|
||
节点：PD: Gemini Image (apikey)
|
||
|
||
参数：
|
||
- api_key: AIzaSyD...
|
||
- project_id: my-project-123
|
||
- location: us-central1
|
||
- prompt: A beautiful landscape with mountains
|
||
- model: gemini-2.5-flash-image
|
||
- aspect_ratio: 16:9
|
||
- resolution: 2K
|
||
```
|
||
|
||
### 示例 4：使用 Flux Kontext 编辑图片
|
||
|
||
```
|
||
节点：PD: Flux Kontext (comfyui_AuthToken)
|
||
|
||
参数：
|
||
- auth_token: eyJhbGciOiJSUzI1NiIsImtpZCI6ImEzOGVhNmEw...
|
||
- prompt: Change the sky to sunset colors
|
||
- model: flux-kontext-pro
|
||
- aspect_ratio: 16:9
|
||
- guidance: 3.0
|
||
- steps: 50
|
||
- input_image: [连接输入图片]
|
||
```
|
||
|
||
---
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **API Key 安全**：
|
||
- 不要在公开的工作流中暴露 API Key
|
||
- 建议使用环境变量或配置文件管理
|
||
|
||
2. **成本控制**：
|
||
- 所有节点都会显示预估成本
|
||
- 实际成本以各平台账单为准
|
||
- 建议设置 API 使用限额
|
||
|
||
3. **超时设置**：
|
||
- GPT/Gemini: 120 秒超时
|
||
- Flux Kontext: 10 分钟超时（包含轮询）
|
||
|
||
4. **错误处理**：
|
||
- 所有节点都有详细的错误日志
|
||
- 检查 ComfyUI 控制台查看详细信息
|
||
|
||
5. **网络要求**：
|
||
- 需要稳定的网络连接
|
||
- 某些地区可能需要代理访问
|
||
|
||
---
|
||
|
||
## 🔧 故障排除
|
||
|
||
### 问题 1：认证失败（401 错误）
|
||
|
||
**ComfyUI AuthToken 版本**：
|
||
- 检查 Auth Token 是否正确
|
||
- Token 可能已过期，重新获取
|
||
- 认证头格式：`Authorization: Bearer {auth_token}`
|
||
|
||
**直接 API Key 版本**：
|
||
- 检查 API Key 格式是否正确
|
||
- 确认 API Key 有效且有余额
|
||
- 认证头格式：`X-API-KEY: {api_key}` （与 ComfyUI 官方 API 节点一致）
|
||
- Gemini 需要确认 Project ID 和 Location 正确
|
||
|
||
### 问题 2：请求超时
|
||
|
||
- 检查网络连接
|
||
- 尝试增加超时时间
|
||
- Flux Kontext 可能需要更长时间，属于正常现象
|
||
|
||
### 问题 3：图片无法生成 / 返回黑图
|
||
|
||
**症状**：节点返回 512x512 的黑色图片
|
||
|
||
**可能原因**：
|
||
1. **API 端点错误**（已修复）：
|
||
- 旧版本的 Gemini AuthToken 节点使用了错误的端点格式
|
||
- 错误：`https://api.comfy.org/proxy/vertexai/gemini/{model}:generateContent`
|
||
- 正确：`https://api.comfy.org/proxy/vertexai/gemini/{model}`
|
||
- **解决方案**：更新到最新版本（v2.1+）
|
||
|
||
2. **模型名称不支持**：
|
||
- 检查控制台是否有 "Unsupported model" 错误
|
||
- 确认使用的模型在支持列表中
|
||
- Gemini AuthToken 版本支持：`gemini-2.5-flash-image`, `gemini-2.5-flash-image-preview`
|
||
|
||
3. **提示词违规**：
|
||
- 检查提示词是否符合内容政策
|
||
- 查看控制台日志获取详细错误信息
|
||
|
||
4. **API 配额不足**：
|
||
- 确认账户有足够的配额/余额
|
||
- 检查 API 使用限制
|
||
|
||
**调试步骤**：
|
||
1. 打开 ComfyUI 控制台
|
||
2. 查找 `[GEMINI_AUTHTOKEN]` 或 `[GEMINI_APIKEY]` 开头的日志
|
||
3. 检查是否有 API Error 信息
|
||
4. 根据错误信息采取相应措施
|
||
|
||
### 问题 4：认证失败（Gemini 节点）
|
||
|
||
- 确认已启用 Vertex AI API
|
||
- 确认 Project ID 正确
|
||
- 确认 Location 支持 Gemini 模型
|
||
- 检查 API Key 权限
|
||
|
||
---
|
||
|
||
## 📚 相关链接
|
||
|
||
- [ComfyUI 官网](https://www.comfy.org)
|
||
- [OpenAI Platform](https://platform.openai.com)
|
||
- [Google Cloud Console](https://console.cloud.google.com)
|
||
- [Black Forest Labs](https://blackforestlabs.ai)
|
||
- [ComfyUI GitHub](https://github.com/comfyanonymous/ComfyUI)
|
||
|
||
---
|
||
|
||
## 📄 许可证
|
||
|
||
本项目遵循 MIT 许可证。
|
||
|
||
---
|
||
|
||
## 🤝 贡献
|
||
|
||
欢迎提交 Issue 和 Pull Request！
|
||
|
||
---
|
||
|
||
## 📧 联系方式
|
||
|
||
如有问题或建议，请通过 GitHub Issues 联系。
|
||
|
||
---
|
||
|
||
**最后更新**：2025-01-12
|
||
**版本**：2.5
|
||
|
||
**更新日志**：
|
||
- 2025-01-12 v2.5: 修复 API Key 版本认证头问题（401 错误），使用 `X-API-KEY` 与官方一致
|
||
- 2025-01-12 v2.4: 新增 Gemini Pro Image (Nano Banana Pro) 节点，支持高分辨率生成
|
||
- 2025-01-12 v2.3: 更新 GPT Image AuthToken 节点参数，匹配官方 ComfyUI API 节点
|
||
- 2025-01-12 v2.2: 添加官方 ComfyUI API 节点的默认 system prompt
|
||
- 2025-01-12 v2.1: 修复 Gemini AuthToken 版本黑图问题，更新模型列表
|
||
- 2025-01-11 v2.0: 初始版本，支持 AuthToken 和 API Key 两种认证方式
|