Skip to content

Commit 9a5a7e8

Browse files
christian-byrnechristian-byrne
authored
Update ComfyUI server API routes documentation (#354)
* [docs] update ComfyUI server API routes documentation - Add missing routes: /ws, /features, /models, /userdata endpoints - Add WebSocket communication section explaining real-time messaging - Improve route descriptions for clarity and accuracy - Organize routes with proper categorization Closes #353
1 parent c6e66be commit 9a5a7e8

File tree

2 files changed

+104
-42
lines changed

2 files changed

+104
-42
lines changed

‎development/comfyui-server/comms_routes.mdx‎

Lines changed: 52 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,58 @@ The prompt queue is defined in `execution.py`, which also defines the `PromptExe
1414

1515
`server.py` defines the following routes:
1616

17-
| path | get/post | purpose |
18-
| ------------------------------ | -------- | ------------------------------------------------------------------------- |
19-
| `/` | get | load the comfy webpage |
20-
| `/embeddings` | get | retrieve a list of the names of embeddings available |
21-
| `/extensions` | get | retrieve a list of the extensions registering a `WEB_DIRECTORY` |
22-
| `/workflow_templates` | get | retrieve a map of custom node modules and associated template workflows |
23-
| `/upload/image` | post | upload an image |
24-
| `/upload/mask` | post | upload a mask |
25-
| `/view` | get | view an image. Lots of options, see `@routes.get("/view")` in `server.py` |
26-
| `/view_metadata`/{folder_name} | get | retrieve metadata for a model |
27-
| `/system_stats` | get | retrieve information about the system (python version, devices, vram etc) |
28-
| `/prompt` | get | retrieve current status |
29-
| `/prompt` | post | submit a prompt to the queue |
30-
| `/object_info` | get | retrieve details of all node types |
31-
| `/object_info/{node_class}` | get | retrieve details of one node type |
32-
| `/history` | get | retrieve the queue history |
33-
| `/history/{prompt_id}` | get | retrieve the queue history for a specific prompt |
34-
| `/history` | post | clear history or delete history item |
35-
| `/queue` | get | retrieve the state of the queue |
36-
| `/interrupt` | post | stop the current workflow |
37-
| `/free` | post | free memory by unloading specified models |
17+
#### Core API Routes
18+
19+
| path | get/post/ws | purpose |
20+
| ------------------------------ | ----------- | ------------------------------------------------------------------------- |
21+
| `/` | get | load the comfy webpage |
22+
| `/ws` | websocket | WebSocket endpoint for real-time communication with the server |
23+
| `/embeddings` | get | retrieve a list of the names of embeddings available |
24+
| `/extensions` | get | retrieve a list of the extensions registering a `WEB_DIRECTORY` |
25+
| `/features` | get | retrieve server features and capabilities |
26+
| `/models` | get | retrieve a list of available model types |
27+
| `/models/{folder}` | get | retrieve models in a specific folder |
28+
| `/workflow_templates` | get | retrieve a map of custom node modules and associated template workflows |
29+
| `/upload/image` | post | upload an image |
30+
| `/upload/mask` | post | upload a mask |
31+
| `/view` | get | view an image. Lots of options, see `@routes.get("/view")` in `server.py` |
32+
| `/view_metadata`/{folder_name} | get | retrieve metadata for a model |
33+
| `/system_stats` | get | retrieve information about the system (python version, devices, vram etc) |
34+
| `/prompt` | get | retrieve current queue status and execution information |
35+
| `/prompt` | post | submit a prompt to the queue |
36+
| `/object_info` | get | retrieve details of all node types |
37+
| `/object_info/{node_class}` | get | retrieve details of one node type |
38+
| `/history` | get | retrieve the queue history |
39+
| `/history/{prompt_id}` | get | retrieve the queue history for a specific prompt |
40+
| `/history` | post | clear history or delete history item |
41+
| `/queue` | get | retrieve the current state of the execution queue |
42+
| `/queue` | post | manage queue operations (clear pending/running) |
43+
| `/interrupt` | post | stop the current workflow execution |
44+
| `/free` | post | free memory by unloading specified models |
45+
| `/userdata` | get | list user data files in a specified directory |
46+
| `/v2/userdata` | get | enhanced version that lists files and directories in structured format |
47+
| `/userdata/{file}` | get | retrieve a specific user data file |
48+
| `/userdata/{file}` | post | upload or update a user data file |
49+
| `/userdata/{file}` | delete | delete a specific user data file |
50+
| `/userdata/{file}/move/{dest}` | post | move or rename a user data file |
51+
| `/users` | get | get user information |
52+
| `/users` | post | create a new user (multi-user mode only) |
53+
54+
### WebSocket Communication
55+
56+
The `/ws` endpoint provides real-time bidirectional communication between the client and server. This is used for:
57+
- Receiving execution progress updates
58+
- Getting node execution status in real-time
59+
- Receiving error messages and debugging information
60+
- Live updates when queue status changes
61+
62+
The WebSocket connection sends JSON messages with different types such as:
63+
- `status` - Overall system status updates
64+
- `execution_start` - When a prompt execution begins
65+
- `execution_cached` - When cached results are used
66+
- `executing` - Updates during node execution
67+
- `progress` - Progress updates for long-running operations
68+
- `executed` - When a node completes execution
3869

3970
### Custom routes
4071

‎zh-CN/development/comfyui-server/comms_routes.mdx‎

Lines changed: 52 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -14,27 +14,58 @@ title: "路由"
1414

1515
`server.py` 定义了以下路由：
1616

17-
| 路径 | get/post | 用途 |
18-
| ------------------------------ | -------- | ---------------------------------------------------------------- |
19-
| `/` | get | 加载 Comfy 网页 |
20-
| `/embeddings` | get | 获取可用的嵌入模型名称列表 |
21-
| `/extensions` | get | 获取注册了 `WEB_DIRECTORY` 的扩展列表 |
22-
| `/workflow_templates` | get | 获取自定义节点模块及其关联模板工作流的映射 |
23-
| `/upload/image` | post | 上传图片 |
24-
| `/upload/mask` | post | 上传蒙版 |
25-
| `/view` | get | 查看图片。更多选项请参见 `server.py` 中的 `@routes.get("/view")` |
26-
| `/view_metadata`/{folder_name} | get | 获取模型的元数据 |
27-
| `/system_stats` | get | 获取系统信息（Python 版本、设备、显存等） |
28-
| `/prompt` | get | 获取当前状态 |
29-
| `/prompt` | post | 提交提示到队列 |
30-
| `/object_info` | get | 获取所有节点类型的详细信息 |
31-
| `/object_info/{node_class}` | get | 获取特定节点类型的详细信息 |
32-
| `/history` | get | 获取队列历史记录 |
33-
| `/history/{prompt_id}` | get | 获取特定提示的队列历史记录 |
34-
| `/history` | post | 清除历史记录或删除历史记录项 |
35-
| `/queue` | get | 获取队列状态 |
36-
| `/interrupt` | post | 停止当前工作流 |
37-
| `/free` | post | 通过卸载指定模型释放内存 |
17+
#### 核心 API 路由
18+
19+
| 路径 | get/post/ws | 用途 |
20+
| ------------------------------ | ----------- | ---------------------------------------------------------------- |
21+
| `/` | get | 加载 Comfy 网页 |
22+
| `/ws` | websocket | 用于与服务器进行实时通信的 WebSocket 端点 |
23+
| `/embeddings` | get | 获取可用的嵌入模型名称列表 |
24+
| `/extensions` | get | 获取注册了 `WEB_DIRECTORY` 的扩展列表 |
25+
| `/features` | get | 获取服务器功能和能力 |
26+
| `/models` | get | 获取可用模型类型列表 |
27+
| `/models/{folder}` | get | 获取特定文件夹中的模型 |
28+
| `/workflow_templates` | get | 获取自定义节点模块及其关联模板工作流的映射 |
29+
| `/upload/image` | post | 上传图片 |
30+
| `/upload/mask` | post | 上传蒙版 |
31+
| `/view` | get | 查看图片。更多选项请参见 `server.py` 中的 `@routes.get("/view")` |
32+
| `/view_metadata`/{folder_name} | get | 获取模型的元数据 |
33+
| `/system_stats` | get | 获取系统信息（Python 版本、设备、显存等） |
34+
| `/prompt` | get | 获取当前队列状态和执行信息 |
35+
| `/prompt` | post | 提交提示到队列 |
36+
| `/object_info` | get | 获取所有节点类型的详细信息 |
37+
| `/object_info/{node_class}` | get | 获取特定节点类型的详细信息 |
38+
| `/history` | get | 获取队列历史记录 |
39+
| `/history/{prompt_id}` | get | 获取特定提示的队列历史记录 |
40+
| `/history` | post | 清除历史记录或删除历史记录项 |
41+
| `/queue` | get | 获取执行队列的当前状态 |
42+
| `/queue` | post | 管理队列操作（清除待处理/运行中的任务） |
43+
| `/interrupt` | post | 停止当前工作流执行 |
44+
| `/free` | post | 通过卸载指定模型释放内存 |
45+
| `/userdata` | get | 列出指定目录中的用户数据文件 |
46+
| `/v2/userdata` | get | 增强版本，以结构化格式列出文件和目录 |
47+
| `/userdata/{file}` | get | 获取特定的用户数据文件 |
48+
| `/userdata/{file}` | post | 上传或更新用户数据文件 |
49+
| `/userdata/{file}` | delete | 删除特定的用户数据文件 |
50+
| `/userdata/{file}/move/{dest}` | post | 移动或重命名用户数据文件 |
51+
| `/users` | get | 获取用户信息 |
52+
| `/users` | post | 创建新用户（仅限多用户模式） |
53+
54+
### WebSocket 通信
55+
56+
`/ws` 端点提供客户端与服务器之间的实时双向通信。用于：
57+
- 接收执行进度更新
58+
- 实时获取节点执行状态
59+
- 接收错误消息和调试信息
60+
- 队列状态变化时的实时更新
61+
62+
WebSocket 连接发送不同类型的 JSON 消息，例如：
63+
- `status` - 整体系统状态更新
64+
- `execution_start` - 当提示执行开始时
65+
- `execution_cached` - 当使用缓存结果时
66+
- `executing` - 节点执行期间的更新
67+
- `progress` - 长时间运行操作的进度更新
68+
- `executed` - 当节点完成执行时
3869

3970
### 自定义路由
4071

0 commit comments

Comments
 (0)