ComfyUI API 技能

---

name: comfyui-api

description: 通过 HTTP API 与 ComfyUI 服务交互，支持工作流提交与执行、队列管理、文件上传和能力探测；自动检测视频工作流并使用合适超时；简洁输出执行结果；当用户需要使用 ComfyUI 生成图像、视频、音频或管理服务时使用

dependency:

python:

- requests>=2.28.0

- websocket-client>=1.4.0

- Pillow>=9.0.0

- pyyaml>=6.0

---

# ComfyUI API 技能

任务目标

前置准备

依赖说明

scripts 脚本所需的依赖包及版本：

requests>=2.28.0
websocket-client>=1.4.0
Pillow>=9.0.0
pyyaml>=6.0

服务地址

工作流目录

`workflows/` 目录用于存储用户上传的工作流 JSON 文件，便于复用和管理。

操作步骤

1. 工作流执行（核心功能）

**使用场景**：提交工作流 JSON 并获取生成的输出文件（支持图像、视频、音频等多种类型）

**执行步骤**：

#### 方式一：使用 workflows 目录中的工作流

python scripts/comfyui_executor.py --workflow my_workflow.json

#### 方式二：使用指定路径的工作流

python scripts/comfyui_executor.py \
  --workflow ./custom_workflow.json \
  --output-dir ./output

#### 方式三：指定服务器地址和超时时间

python scripts/comfyui_executor.py \
  --workflow my_workflow.json \
  --server-url http://192.168.1.100:8188 \
  --timeout 600

**参数说明**：

**支持的输出类型**：

**超时自动检测**：

**输出示例**：

⏳ 执行中... 45 秒
✓ 已下载 2 个文件：图像 2 个
✓ 任务完成: abc123-def456

输出文件：
  output/image_001.png
  output/image_002.png

**智能体职责**：

2. 工作流管理

#### 列出工作流

查看 `workflows/` 目录中存储的所有工作流：

python scripts/workflow_manager.py --action list

**输出内容**：

#### 查看工作流详情

查看指定工作流的详细信息和内容：

python scripts/workflow_manager.py --action show --name my_workflow.json

#### 删除工作流

删除不需要的工作流：

python scripts/workflow_manager.py --action delete --name old_workflow.json

**智能体职责**：

3. 队列管理

**使用场景**：查看当前执行队列或中断正在执行的任务

**查看队列**：

python scripts/queue_manager.py --action list

**中断执行**：

python scripts/queue_manager.py --action interrupt

**智能体职责**：

4. 文件上传

**使用场景**：上传各种类型的文件到 ComfyUI（图像、视频、音频、模型等）

**支持的文件类型**：

**自动检测类型上传**：

# 自动检测文件类型
python scripts/file_uploader.py --file ./reference.png
python scripts/file_uploader.py --file ./video.mp4
python scripts/file_uploader.py --file ./audio.wav
python scripts/file_uploader.py --file ./model.glb

**指定类型上传**：

# 上传图像
python scripts/file_uploader.py --type image --file ./reference.png

# 上传蒙版
python scripts/file_uploader.py --type mask --file ./mask.png --subfolder input

# 上传视频
python scripts/file_uploader.py --type video --file ./input_video.mp4

# 上传音频
python scripts/file_uploader.py --type audio --file ./background_music.mp3

# 上传 3D 模型
python scripts/file_uploader.py --type model --file ./character.obj

**上传到指定子目录**：

python scripts/file_uploader.py --file ./reference.png --subfolder my_project

**输出示例**：

✓ 文件上传成功
文件名: reference.png
类型: image
子文件夹: input
大小: 1.2 MB

在工作流中使用：
  路径: input/reference.png

**智能体职责**：

5. 能力探测

**使用场景**：了解 ComfyUI 服务支持的节点、模型、embeddings 和系统状态

**获取节点定义**：

# 获取所有节点
python scripts/capability_probe.py --type nodes

# 获取单个节点详情
python scripts/capability_probe.py --type nodes --node-class KSampler

**获取模型列表**：

# 获取所有模型
python scripts/capability_probe.py --type models

# 获取特定文件夹的模型
python scripts/capability_probe.py --type models --folder checkpoints

**获取其他资源**：

# 获取 embeddings 列表
python scripts/capability_probe.py --type embeddings

# 获取已安装扩展
python scripts/capability_probe.py --type extensions

# 获取服务器功能特性
python scripts/capability_probe.py --type features

# 获取工作流模板
python scripts/capability_probe.py --type templates

# 获取模型元数据
python scripts/capability_probe.py --type metadata --model sd_xl_base.safetensors

# 获取系统状态
python scripts/capability_probe.py --type system

**智能体职责**：

6. 内存和历史管理

**使用场景**：管理 ComfyUI 内存使用和清理执行历史

**释放内存**：

# 基本内存释放
python scripts/memory_manager.py --action free

# 卸载所有模型
python scripts/memory_manager.py --action free --unload-models

# 释放 50% 内存
python scripts/memory_manager.py --action free --free-memory 0.5

**清理历史**：

# 清空所有历史
python scripts/memory_manager.py --action clear-history

# 删除特定历史记录
python scripts/memory_manager.py --action clear-history --prompt-id task-id

**查看队列状态**：

python scripts/memory_manager.py --action status

**智能体职责**：

资源索引

参考文档

核心脚本

注意事项

工作流管理

执行相关

- 图像生成：默认 5 分钟，可通过 `--timeout` 调整

- 视频生成：自动检测并使用 15 分钟，或手动指定更长时间

- 长时间任务：建议设置更长的超时时间（如 `--timeout 1200` 表示 20 分钟）

安全性

使用示例

示例 1：执行基础文生图

**步骤**：

1. 智能体创建工作流并保存到 `workflows/` 目录

2. 执行工作流（自动检测超时）：

```bash

python scripts/comfyui_executor.py --workflow txt2img_default.json

```

示例 2：执行视频生成工作流

**步骤**：

1. 视频工作流会自动使用 15 分钟超时：

```bash

python scripts/comfyui_executor.py --workflow video_gen.json

```

2. 或手动指定更长的超时时间：

```bash

python scripts/comfyui_executor.py --workflow video_gen.json --timeout 1200

```

示例 3：使用自定义配置执行

**步骤**：

临时使用不同的服务器地址和超时时间：

python scripts/comfyui_executor.py \
  --workflow my_workflow.json \
  --server-url http://192.168.1.100:8188 \
  --timeout 1200

示例 4：管理多个工作流

**步骤**：

1. 列出所有工作流：

```bash

python scripts/workflow_manager.py --action list

```

2. 智能体分析并推荐合适的工作流

3. 执行选定的工作流

示例 5：探测服务器能力

**步骤**：

1. 获取可用模型：

```bash

python scripts/capability_probe.py --type models

```

2. 智能体根据模型列表推荐合适的工作流配置

3. 执行工作流