WebSocket 和 HTTP API

相关源文件

• custom_nodes/websocket_image_save.py
• script_examples/basic_api_example.py
• script_examples/websockets_api_example.py
• script_examples/websockets_api_example_ws_images.py

本文档涵盖了 ComfyUI 用于执行工作流和接收实时更新的程序化接口。该 API 同时提供了用于请求-响应操作的 HTTP 端点和用于工作流执行期间实时通信的 WebSocket 连接。

有关与云服务进行外部 API 集成的信息，请参阅外部 API 集成。有关前端 Web 界面配置的信息，请参阅前端管理。

API 架构概述

ComfyUI 提供了两个互补的接口用于程序化交互：用于工作流提交和数据检索的 REST 式 HTTP API，以及用于实时执行监控和实时更新的 WebSocket API。

来源：script_examples/basic_api_example.py102-114 script_examples/websockets_api_example.py13-17 script_examples/websockets_api_example.py154-156

HTTP API 端点

HTTP API 提供用于工作流提交和数据检索的同步端点。所有端点都使用默认服务器地址 127.0.0.1:8188。

提示提交端点

方法	路径	目的
POST	/prompt	提交工作流以执行

请求格式

响应格式

历史记录检索端点

方法	路径	目的
GET	/history/{prompt_id}	获取执行结果和元数据

响应格式

图像检索端点

方法	路径	目的
GET	/view?filename={name}&subfolder={path}&type={type}	下载生成的图像

来源：script_examples/basic_api_example.py102-114 script_examples/websockets_api_example.py25-27 script_examples/websockets_api_example.py19-23

WebSocket API

WebSocket API 实现了工作流执行期间的实时通信，提供状态更新、进度信息和实时预览图像。

连接建立

WebSocket 连接使用端点 /ws?clientId={unique_id} 建立，其中 clientId 允许将消息与特定客户端会话相关联。

消息类型

WebSocket API 在工作流执行期间发送多种类型的消息

状态消息（JSON）

二进制预览图像

• 8 字节头：4 字节消息类型 + 4 字节图像格式
• 剩余字节：图像数据（通常为 PNG 格式）

来源：script_examples/websockets_api_example.py32-44 script_examples/websockets_api_example_ws_images.py32-49

工作流提示格式

工作流被定义为 JSON 对象，其中每个键代表一个节点 ID，并包含节点的类类型和输入连接。

节点定义结构

连接语法

节点输出通过格式 ["source_node_id", output_index] 引用，其中 output_index 是输出槽的零基索引。

来源：script_examples/basic_api_example.py13-100 script_examples/websockets_api_example.py58-145

实时通信流程

WebSocket API 允许监控工作流执行进度并在无需轮询的情况下接收中间结果。

执行监控模式

消息处理逻辑

客户端处理 WebSocket 消息以跟踪执行状态

1. JSON 消息：解析以获取执行状态和节点进度
2. 二进制消息：在生成过程中处理预览图像
3. 完成检测：node: null 表示执行完成

来源：script_examples/websockets_api_example.py32-44 script_examples/websockets_api_example_ws_images.py32-49

图像处理方法

ComfyUI 通过 API 提供了多种接收生成图像的方法。

传统的基于文件的方法

1. 通过 HTTP /prompt 端点执行工作流
2. 通过 WebSocket 消息监控完成情况
3. 通过 HTTP /history/{prompt_id} 端点检索结果
4. 通过 HTTP /view 端点下载图像

直接 WebSocket 图像传输

使用 SaveImageWebsocket 节点，可以直接通过 WebSocket 连接接收图像，而无需文件系统存储。

SaveImageWebsocket 节点集成

SaveImageWebsocket 类通过与进度系统集成并将二进制图像数据与 8 字节头格式一起发送，实现了通过 WebSocket 连接直接传输图像。

来源：script_examples/websockets_api_example.py19-56 script_examples/websockets_api_example_ws_images.py45-48 custom_nodes/websocket_image_save.py13-36

实际实现示例

基本 HTTP 工作流提交

最简单的 API 用法包括提交工作流并轮询其完成情况

基于 WebSocket 的执行监控

如需实时更新，请建立 WebSocket 连接并处理消息

客户端 ID 相关性

使用唯一的客户端 ID 将 WebSocket 消息与特定执行请求相关联

来源：script_examples/basic_api_example.py102-114 script_examples/websockets_api_example.py29-39 script_examples/websockets_api_example.py10-17