ComfyUI Agnes AI Extension

ComfyUI 自定义节点插件，让你在 ComfyUI 中直接调用 Agnes AI 的全模态模型。

功能节点

节点名称	功能	模型
Agnes API Key Config	🔑 持久化保存 API Key（推荐首次运行）	—
Agnes LLM Chat	LLM 文本对话	agnes-2.0-flash
Agnes Image Reverse Prompt	图像反推提示词	agnes-2.0-flash (vision)
Agnes Image-to-Image	图生图 / 图片编辑（支持多图输入）	agnes-image-2.1-flash
Agnes Text-to-Image	文生图	agnes-image-2.1-flash
Agnes Image-to-Video	图生视频（支持多图/关键帧）	agnes-video-v2.0
Agnes Text-to-Video	文生视频	agnes-video-v2.0

安装方法

方法一：Git 克隆

cd ComfyUI/custom_nodes
git clone https://github.com/yourusername/comfyui_agnes_ai.git
cd comfyui_agnes_ai
pip install -r requirements.txt

方法二：手动安装

1. 下载此插件文件夹
2. 将其放入 ComfyUI/custom_nodes/ 目录
3. 安装依赖：pip install -r requirements.txt
4. 重启 ComfyUI

获取 API Key

1. 访问 https://platform.agnes-ai.com/
2. 注册/登录账号
3. 创建 API Key（目前免费）

快速开始：配置 API Key

推荐方式 — 使用 Agnes API Key Config 节点：

1. 在节点菜单 → Agnes AI → 添加 Agnes API Key Config
2. 在 api_key 输入框填入你的 API Key（例如 sk-xxx...）
3. 运行一次（Ctrl+Enter / Queue Prompt）
4. Key 会自动保存到插件目录的 api_key_config.json 文件中
5. 之后所有其他 Agnes 节点的 api_key 字段留空即可自动加载

备用方式 — 环境变量或直接输入：

• 环境变量：设置 AGNES_API_KEY（优先级最高）
• 直接输入：在每个节点的 api_key 字段手动填写

API Key 加载优先级

环境变量 AGNES_API_KEY  >  api_key_config.json  >  运行时回退加载  >  节点输入框手动填写

注意：api_key widget 始终显示灰色 placeholder sk-...，不会明文显示真实 Key。

节点使用说明

🔑 Agnes API Key Config

• 首次运行即可，将 API Key 持久化保存
• Key 以明文存储在 api_key_config.json（仅本机可访问）
• 设置 clear_key = YES 可清除已保存的 Key
• 输出 status 和 masked_key 供确认

Agnes LLM Chat

• 输入文本消息，获取 LLM 回复
• 可选设置 System Prompt 控制 AI 行为
• 可调节 temperature（0.0-2.0）和 max_tokens

Agnes Image Reverse Prompt

• 输入图片，自动分析并生成可复现该图片的提示词
• 同时输出详细版和简洁版提示词

Agnes Image-to-Image（支持多图输入）

• 输入参考图 + 文本描述，生成编辑后的图片
• 支持最多 4 张参考图同时输入
• 画质选择：1K / 2K / 4K
• 宽高比：1:1, 2:3, 3:4, 4:5, 9:16, 9:21, 3:2, 4:3, 5:4, 16:9, 21:9
• Strength 控制修改程度（0=尽量保持原图，1=自由发挥）
• 输出：images (IMAGE) + resolution (STRING)

Agnes Text-to-Image

• 纯文本描述生成图片
• 画质选择：1K / 2K / 4K
• 宽高比：1:1, 2:3, 3:4, 4:5, 9:16, 9:21, 3:2, 4:3, 5:4, 16:9, 21:9
• 可一次生成最多 4 张
• 输出：images (IMAGE) + resolution (STRING)

Agnes Image-to-Video（支持多图/关键帧）

• 一张图或多张图生成视频动画
• 支持设置关键帧（start -> end）
• 画质选择：1K / 2K
• 宽高比：1:1, 2:3, 3:4, 4:5, 9:16, 9:21, 3:2, 4:3, 5:4, 16:9, 21:9
• 可调节帧数（9-441，8n+1 格式）、帧率（8-60fps）
• 输出：video (VIDEO) + resolution (STRING)
• 视频保存到 ComfyUI/output/agnes_videos/ 目录

Agnes Text-to-Video

• 纯文本描述生成视频
• 画质选择：1K / 2K
• 宽高比：1:1, 2:3, 3:4, 4:5, 9:16, 9:21, 3:2, 4:3, 5:4, 16:9, 21:9
• 可调节帧数（9-441，8n+1）、帧率（8-60fps）、seed
• 输出：video (VIDEO) + resolution (STRING)
• 视频保存到 ComfyUI/output/agnes_videos/ 目录

视频输出类型

视频节点输出类型按优先级自动选择：

环境	输出类型	说明
ComfyUI v1.7+ 自带	VIDEO	原生 VideoFromFile，可直连 SaveVideo
安装了 VHS	VHS_VIDEOINFO	dict 格式，兼容视频工作流
都没有	STRING	文件路径字符串

画质 × 宽高比对照表

图片生成（1K / 2K / 4K）

比例	1K	2K	4K
1:1	1024×1024	2048×2048	4096×4096
16:9	1816×1024	3640×2048	7280×4096
9:16	1024×1816	2048×3640	4096×7280
21:9	2384×1024	4776×2048	9552×4096
9:21	1024×2384	2048×4776	4096×9552

视频生成（1K / 2K）

比例	1K	2K
1:1	1024×1024	2048×2048
16:9	1816×1024	3640×2048
9:16	1024×1816	2048×3640

错误处理

• API 5xx 错误（502/503/504/524）：自动重试 3 次，指数退避（3s/6s/12s）
• 连接超时：自动重试 + 中文错误提示
• Cloudflare 错误页：自动解析为中文可读提示
• CUDA OOM（服务器端）：自动识别并给出降参数建议

技术架构

comfyui_agnes_ai/
├── __init__.py              # 插件入口，注册 7 个节点
├── config.yaml              # 默认配置
├── requirements.txt         # 依赖
├── README.md                # 本文档
├── api/
│   └── __init__.py          # AgnesClient API 封装（Chat / Image / Video）
├── nodes/
│   ├── __init__.py
│   ├── api_key_config.py    # API Key 持久化节点
│   ├── llm_chat.py          # LLM 对话
│   ├── image_reverse.py     # 图像反推
│   ├── text2img.py          # 文生图
│   ├── img2img.py           # 图生图（多图）
│   ├── text2video.py        # 文生视频
│   └── img2video.py         # 图生视频（多图/关键帧）
└── web/js/                  # 前端扩展目录（预留）

更新日志

v1.6.0 — 原生 VIDEO 类型输出

• 视频节点输出口支持 ComfyUI 原生 VIDEO 类型（v1.7+）
• 三级检测链：comfy_api VIDEO → VHS_VIDEOINFO → STRING
• 修复 remixed_from_video_id 字段名（API 实际返回的 URL 字段）
• VIDEO 类型出错时 raise 而非返回字符串（避免下游 SaveVideo 崩溃）

v1.4.0 — API 错误处理优化

• HTML 错误页（Cloudflare 5xx）自动解析为中文提示
• 5xx/429 自动重试 3 次，连接超时自动重试
• Chat / Image / Video 三个 API 统一使用重试机制

v1.3.0 — 图片节点画质与分辨率

• text2img / img2img 新增 quality（1K/2K/4K）+ aspect_ratio（11种）
• 自动计算实际像素（对齐 8 的倍数）
• 新增 resolution 输出口

v1.2.0 — 视频输出路径优化

• 视频从系统临时目录 → ComfyUI/output/agnes_videos/
• generate_video() 新增 output_dir 参数

v1.1.0 — API Key 持久化

• 新增 AgnesAPIKeyConfig 节点，Key 保存到 api_key_config.json
• api_key widget 统一为空字符串，运行时从 config 自动加载

v1.0.0 — 初始版本

• 7 个节点：API Key Config、LLM Chat、Image Reverse、Text-to-Image、Image-to-Image、Text-to-Video、Image-to-Video

注意事项

• 视频生成是异步任务，通常需要 2-6 分钟
• 免费 API 高峰期可能有排队（503）或 GPU OOM（500），降低画质/帧数可提高成功率
• 建议首次使用先测试文生图，确认 API Key 正常工作
• 多张图片同时生成会增加等待时间

许可证

MIT License