API 和扩展

相关源文件

• comfy_api_nodes/apinode_utils.py
• comfy_api_nodes/apis/bfl_api.py
• comfy_api_nodes/apis/client.py
• comfy_api_nodes/nodes_bfl.py
• comfy_api_nodes/nodes_ideogram.py
• comfy_api_nodes/nodes_kling.py
• comfy_api_nodes/nodes_luma.py
• comfy_api_nodes/nodes_minimax.py
• comfy_api_nodes/nodes_openai.py
• comfy_api_nodes/nodes_pika.py
• comfy_api_nodes/nodes_pixverse.py
• comfy_api_nodes/nodes_recraft.py
• custom_nodes/websocket_image_save.py
• requirements.txt
• script_examples/basic_api_example.py
• script_examples/websockets_api_example.py
• script_examples/websockets_api_example_ws_images.py

本文档涵盖了 ComfyUI 的外部接口和可扩展性机制，包括用于程序化访问的内置 HTTP/WebSocket API、集成外部 AI 服务的框架以及创建自定义节点和扩展的系统。

有关核心节点系统架构的信息，请参阅 节点系统。有关工作流执行和 PromptServer 的详细信息，请参阅 执行系统。

ComfyUI HTTP 和 WebSocket API

ComfyUI 提供 REST 和 WebSocket API 以实现程序化交互，使外部应用程序能够提交工作流、监控执行情况并检索结果。

HTTP API 端点

HTTP API 基于 aiohttp 运行，并提供用于工作流管理的端点。

关键 HTTP 端点

• POST /prompt - 提交工作流以供执行
• GET /history/{prompt_id} - 检索执行结果
• GET /view - 下载生成的图像/视频
• POST /interrupt - 取消正在运行的工作流

示例工作流提交

来源： script_examples/basic_api_example.py102-125 requirements.txt14

WebSocket API

WebSocket 接口提供工作流执行期间的实时更新。

WebSocket 消息类型

• executing - 节点执行状态更新
• 二进制数据 - 实时图像预览和结果
• progress - 执行进度信息

连接模式

来源： script_examples/websockets_api_example.py154-156 script_examples/websockets_api_example_ws_images.py147-149

通过 WebSocket 流式传输图像

ComfyUI 支持通过自定义节点通过 WebSocket 连接流式传输全分辨率图像。

该 SaveImageWebsocket 节点以二进制数据形式发送图像，并带有指示消息类型和格式的 8 字节头部。

来源： custom_nodes/websocket_image_save.py6-11 script_examples/websockets_api_example_ws_images.py44-48

外部 API 集成框架

ComfyUI 通过 API 节点提供了一个用于集成外部 AI 服务的全面框架，使工作流能够利用云端模型和服务。

API 客户端架构

核心 API 客户端框架处理身份验证、重试以及请求/响应处理。

核心类

• ApiClient - 带有重试逻辑和身份验证的 HTTP 客户端
• ApiEndpoint - 带有请求/响应模型的端点定义
• SynchronousOperation - 即时请求/响应模式
• PollingOperation - 异步任务轮询模式

来源： comfy_api_nodes/apis/client.py161-189 comfy_api_nodes/apis/client.py765-805 comfy_api_nodes/apis/client.py894-954

请求/响应处理

API 操作使用 Pydantic 模型来确保类型安全和进行验证。

示例 API 端点定义

来源： comfy_api_nodes/apis/client.py738-763 comfy_api_nodes/nodes_openai.py327-344

身份验证和错误处理

该框架提供了强大的身份验证和错误处理机制。

认证方法

• 通过 AUTH_TOKEN_COMFY_ORG 进行 Bearer 令牌身份验证
• 通过 API_KEY_COMFY_ORG 进行 API 密钥身份验证
• 支持按请求进行身份验证覆盖

错误分类

• LocalNetworkError - Internet 连接问题
• ApiServerError - 外部服务不可用
• 自动重试瞬态错误（5xx、429、408）

来源： comfy_api_nodes/apis/client.py236-245 comfy_api_nodes/apis/client.py118-131 comfy_api_nodes/apis/client.py377-401

外部服务集成

ComfyUI 包含用于集成主流 AI 服务提供商的节点。

图像生成服务

服务能力

• 文本到图像生成
• 图像编辑和修复
• 风格迁移和操作
• 高分辨率放大

来源： comfy_api_nodes/nodes_openai.py85-164 comfy_api_nodes/nodes_bfl.py131-271 comfy_api_nodes/nodes_ideogram.py249-381

视频生成服务

视频能力

• 文本到视频生成
• 图像到视频动画
• 相机控制和运动
• 视频特效和转场

来源： comfy_api_nodes/nodes_kling.py400-531 comfy_api_nodes/nodes_pika.py257-314 comfy_api_nodes/nodes_luma.py274-389

异步 API 的轮询操作

许多视频生成 API 使用需要轮询的异步处理模式。

轮询实现

来源：comfy_api_nodes/apis/client.py894-954 comfy_api_nodes/nodes_kling.py112-135

实用函数与数据处理

API框架包含用于数据转换和文件处理的综合实用工具

图像和视频处理

主要实用函数

• tensor_to_base64_string() - 将张量转换为base64以便API传输
• download_url_to_video_output() - 将URL中的视频下载到ComfyUI格式
• upload_file_to_comfyapi() - 上传文件到ComfyUI存储并进行身份验证
• validate_aspect_ratio() - 验证纵横比约束

来源：comfy_api_nodes/apinode_utils.py281-301 comfy_api_nodes/apinode_utils.py33-47 comfy_api_nodes/apinode_utils.py339-376

身份验证和配置

API节点使用隐藏输入进行身份验证配置

身份验证凭据通过 auth_kwargs 传递给 API 客户端框架。

来源：comfy_api_nodes/nodes_openai.py153-157 script_examples/basic_api_example.py105-111

扩展开发

ComfyUI 支持通过自定义节点和 API 集成来实现可扩展性

自定义节点开发

开发者可以通过扩展 ComfyNodeABC 来创建自定义节点

自定义节点结构

来源：comfy_api_nodes/nodes_openai.py85-164 custom_nodes/websocket_image_save.py13-44

集成模式

API节点遵循一致的模式来进行外部服务集成

1. 请求准备 - 将 ComfyUI 数据转换为 API 格式
2. 身份验证 - 应用来自隐藏输入的凭据
3. API 通信 - 使用 SynchronousOperation 或 PollingOperation
4. 响应处理 - 将 API 响应转换为 ComfyUI 格式
5. 错误处理 - 提供用户友好的错误消息

该框架支持快速开发新的 API 集成，同时在所有外部服务节点中保持一致性和可靠性。

来源：comfy_api_nodes/apis/client.py806-884 comfy_api_nodes/apinode_utils.py65-120