comfyui-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ComfyUI API Skill

ComfyUI API 技能

Connect to ComfyUI's REST API to execute workflows, monitor progress, and retrieve outputs.

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

Configuration

配置项

Default URL:
```
http://127.0.0.1:8188
```
Custom URL: Set in project manifest or pass as parameter
Timeout: 30s for API calls, no timeout for generation polling

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

Two Modes

两种模式

Online Mode (ComfyUI Running)

在线模式（ComfyUI运行中）

Full API access. Preferred mode for interactive work.

Test connection:
```
GET /system_stats
```
Discover capabilities: Use
```
comfyui-inventory
```
skill
Queue workflow:
```
POST /prompt
```
Poll for results:
```
GET /history/{prompt_id}
```
every 5 seconds
Retrieve outputs:
```
GET /view?filename=...
```

拥有完整API访问权限，是交互式工作的首选模式。

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

Offline Mode (No Server)

离线模式（无服务器）

Export workflow JSON for manual loading in ComfyUI.

Generate workflow JSON following ComfyUI's format

Save to

projects/{project}/workflows/{name}.json

Instruct user to drag-drop into ComfyUI

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

按照ComfyUI格式生成工作流JSON

保存至

projects/{project}/workflows/{name}.json

指导用户将文件拖放至ComfyUI中

API Operations

API操作

Check Server Status

检查服务器状态

bash

curl http://127.0.0.1:8188/system_stats

Response fields:

```
system.os
```
: Operating system
```
system.comfyui_version
```
: Version string
```
devices[0].name
```
: GPU name
```
devices[0].vram_total
```
: Total VRAM bytes
```
devices[0].vram_free
```
: Free VRAM bytes

bash

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字节数

Queue a Workflow

工作流排队

bash

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 format:

json

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

Each node is keyed by a string ID. Inputs reference other nodes as

["{node_id}", {output_index}]

Response:

json

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

bash

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格式：

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}]

格式引用其他节点。

响应：

json

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

Poll for Completion

轮询完成状态

bash

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

Incomplete: Returns

{}

(empty object) Complete: Returns execution data with outputs:

json

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

bash

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

未完成：返回

{}

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

json

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

Retrieve Output Image

获取输出图片

bash

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

bash

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

Upload Reference Image

上传参考图片

bash

curl -X POST http://127.0.0.1:8188/upload/image \
  -F "image=@reference.png" \
  -F "subfolder=input" \
  -F "type=input"

bash

curl -X POST http://127.0.0.1:8188/upload/image \
  -F "image=@reference.png" \
  -F "subfolder=input" \
  -F "type=input"

Cancel Current Generation

取消当前生成任务

bash

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

bash

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

Free VRAM

释放VRAM

bash

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

bash

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

Polling Strategy

轮询策略

ComfyUI doesn't support WebSocket in CLI context. Use REST polling:

Queue workflow via
```
POST /prompt
```
→ get
```
prompt_id
```
Poll
```
GET /history/{prompt_id}
```
every 5 seconds
On empty response: generation in progress, continue polling
On populated response: check
```
status.completed
```
If
```
completed: true
```
, extract outputs
If error in status, route to
```
comfyui-troubleshooter
```

Timeout: Warn user after 10 minutes of polling. Video generation (Wan 14B) can take 15-30 minutes.

在CLI环境下ComfyUI不支持WebSocket，需使用REST轮询：

通过
```
POST /prompt
```
提交工作流 → 获取
```
prompt_id
```
每5秒轮询一次
```
GET /history/{prompt_id}
```
若返回空响应：生成任务进行中，继续轮询
若返回非空响应：检查
```
status.completed
```
字段
若
```
completed: true
```
，提取输出结果
若状态中存在错误，跳转至
```
comfyui-troubleshooter
```

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

Workflow Validation

工作流验证

Before queuing any workflow:

Read
```
state/inventory.json
```
(via
```
comfyui-inventory
```
)
For each node in workflow: verify
```
class_type
```
exists in installed nodes
For each model reference: verify file exists in installed models
Flag missing items with:
- Node: suggest
```
ComfyUI-Manager
```
  install command
- Model: provide download link from
```
references/models.md
```
- Version mismatch: suggest update

在提交任何工作流前：

读取
```
state/inventory.json
```
（通过
```
comfyui-inventory
```
技能）
对工作流中的每个节点：验证
```
class_type
```
是否存在于已安装节点中
对每个模型引用：验证文件是否存在于已安装模型中
标记缺失项并给出建议：
- 节点：建议使用
```
ComfyUI-Manager
```
  安装命令
- 模型：提供
```
references/models.md
```
  中的下载链接
- 版本不匹配：建议更新

Error Handling

错误处理

Error	Cause	Action
Connection refused	ComfyUI not running	Switch to offline mode, save JSON
400 Bad Request	Invalid workflow JSON	Validate node connections
500 Internal Error	ComfyUI crash	Suggest restart, check logs
Timeout (no response)	Server overloaded	Wait and retry once

错误类型	原因	处理方式
连接被拒绝	ComfyUI未运行	切换至离线模式，保存JSON文件
400 Bad Request	工作流JSON无效	验证节点连接关系
500 Internal Error	ComfyUI崩溃	建议重启并检查日志
超时（无响应）	服务器过载	等待后重试一次

Reference

参考

Full API documentation:

foundation/api-quick-ref.md

完整API文档：

foundation/api-quick-ref.md