7BEII-comfyui-PD_comfy-api-node/py/README.md

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 官网
• OpenAI Platform
• Google Cloud Console
• Black Forest Labs
• ComfyUI GitHub

---

📄 许可证

本项目遵循 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 两种认证方式