comfyui-api

ComfyUI API 技能

连接到 ComfyUI 的 REST API，以执行工作流、监控进度并获取输出。

配置

• 默认 URL：http://127.0.0.1:8188
• 自定义 URL：在项目清单中设置，或作为参数传入
• 超时：API 调用为 30s，生成轮询不设超时

两种模式

在线模式（ComfyUI 正在运行）

可完整访问 API。交互式工作时的首选模式。

1. 测试连接：GET /system_stats
2. 发现功能：使用 comfyui-inventory 技能
3. 加入工作流队列：POST /prompt
4. 轮询结果：每 5 秒调用一次 GET /history/{prompt_id}
5. 获取输出：GET /view?filename=...

离线模式（无服务）

导出工作流 JSON，以便在 ComfyUI 中手动加载。

1. 按照 ComfyUI 的格式生成工作流 JSON
2. 保存到 projects/{project}/workflows/{name}.json
3. 告知用户将其拖放到 ComfyUI 中

API 操作

检查服务状态

curl http://127.0.0.1:8188/system_stats

响应字段：

• system.os：操作系统
• system.comfyui_version：版本字符串
• devices[0].name：GPU 名称
• devices[0].vram_total：VRAM 总字节数
• devices[0].vram_free：VRAM 可用字节数

将工作流加入队列

curl -X POST http://127.0.0.1:8188/prompt \
  -H "Content-Type: application/json" \
  -d '{"prompt": WORKFLOW_JSON, "client_id": "video-agent"}'

WORKFLOW_JSON 格式：

{
  "1": {
    "class_type": "LoadCheckpoint",
    "inputs": {
      "ckpt_name": "flux1-dev.safetensors"
    }
  },
  "2": {
    "class_type": "CLIPTextEncode",
    "inputs": {
      "text": "photorealistic portrait...",
      "clip": ["1", 1]
    }
  }
}

每个节点以字符串 ID 为键。输入通过 ["{node_id}", {output_index}] 引用其他节点。

响应：

{"prompt_id": "abc-123-def", "number": 1}

轮询完成状态

curl http://127.0.0.1:8188/history/abc-123-def

未完成：返回 {}（空对象） 已完成：返回包含输出的执行数据：

{
  "abc-123-def": {
    "outputs": {
      "9": {
        "images": [{"filename": "ComfyUI_00001.png", "subfolder": "", "type": "output"}]
      }
    },
    "status": {"completed": true}
  }
}

获取输出图像

curl "http://127.0.0.1:8188/view?filename=ComfyUI_00001.png&subfolder=&type=output" -o output.png

上传参考图像

curl -X POST http://127.0.0.1:8188/upload/image \
  -F "[email protected]" \
  -F "subfolder=input" \
  -F "type=input"

取消当前生成

curl -X POST http://127.0.0.1:8188/interrupt

释放 VRAM

curl -X POST http://127.0.0.1:8188/free \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true}'

轮询策略

ComfyUI 在 CLI 环境中不支持 WebSocket。请使用 REST 轮询：

1. 通过 POST /prompt 将工作流加入队列 → 获取 prompt_id
2. 每 5 秒轮询一次 GET /history/{prompt_id}
3. 响应为空：生成仍在进行，继续轮询
4. 响应不为空：检查 status.completed
5. 如果 completed: true，提取输出
6. 如果状态中有错误，将请求转交给 comfyui-troubleshooter

超时：轮询 10 分钟后提醒用户。视频生成（Wan 14B）可能需要 15-30 分钟。

工作流验证

将任何工作流加入队列前：

1. 读取 state/inventory.json（通过 comfyui-inventory）
2. 对工作流中的每个节点：确认已安装节点中存在对应的 class_type
3. 对每个模型引用：确认文件存在于已安装模型中
4. 对缺失项进行标记，并：
   • 节点：建议使用 ComfyUI-Manager 安装命令
   • 模型：提供 references/models.md 中的下载链接
   • 版本不匹配：建议更新

错误处理

错误	原因	操作
Connection refused	ComfyUI 未运行	切换到离线模式，保存 JSON
400 Bad Request	工作流 JSON 无效	验证节点连接
500 Internal Error	ComfyUI 崩溃	建议重启并检查日志
Timeout (no response)	服务过载	等待后重试一次

参考

完整 API 文档：foundation/api-quick-ref.md