跳转到主要内容
实验性 API: 此 API 目前处于实验阶段,可能会发生变更。端点、请求/响应格式和行为可能会在不另行通知的情况下进行修改。

Comfy Cloud API

Comfy Cloud API 提供以编程方式访问 Comfy Cloud 的能力,可在云端基础设施上运行工作流。该 API 与本地 ComfyUI 的 API 兼容,便于迁移现有集成。
需要订阅: API 访问权限在 StandardCreatorPro 等级提供。Free 等级不包含 API 访问权限。详情请参阅定价方案

积分与用量

API 请求消耗的是与 Comfy Cloud 网页端相同的每月积分配额——不存在单独的 API 积分池。每个等级的包含积分、加购选项以及单次工作流运行时长上限对 API 任务和网页端任务完全相同。Standard、Creator 和 Pro 等级的每月积分数量请参阅定价方案。如果在月中用尽积分,可在账户面板中购买加购包。

基础 URL

身份验证

所有 API 请求都需要通过 X-API-Key 请求头传递 API 密钥。

获取 API 密钥

请参阅获取 API 密钥了解如何创建和管理 Cloud API 密钥。

使用 API 密钥

在每个请求中通过 X-API-Key 请求头传递您的 API 密钥:

核心概念

工作流

ComfyUI 工作流是描述节点图的 JSON 对象。API 接受 API 格式 的工作流(以节点 ID 为键,包含 class_type、inputs 等),该格式由 ComfyUI 前端的”导出工作流 (API)“选项导出。

任务

当您提交工作流时,会创建一个任务。任务以异步方式执行:
  1. 通过 POST /api/prompt 提交工作流
  2. 收到 prompt_id(任务 ID)
  3. 通过 WebSocket 监控进度或轮询状态
  4. 完成后获取输出

并行执行(并发任务)

API 用户可以同时提交多个工作流,无需等待之前的任务完成。只需发送多个 POST /api/prompt 请求即可——不需要特殊的请求头或参数。调度器会根据您的订阅等级限制并行运行任务。
订阅等级并发任务数
Standard1
Creator3
Pro5
超出并发限制的任务将正常排队,并在有空闲槽位时自动执行。
并行执行目前仅通过 API 提供。请查看定价方案了解订阅详情。

示例:并行提交多个任务

输出

生成的内容(图像、视频、音频)存储在云存储中。输出文件可通过 /api/view 端点下载,该端点会返回 302 重定向到临时签名 URL。

快速入门

以下是完整示例,展示如何提交工作流、监控进度并获取输出:

步骤 1:提交工作流

步骤 2:监控任务进度

您可以使用轮询或 WebSocket 来监控任务完成情况,以便获取实时更新。

选项 A:轮询(简单)

任务状态值: API 返回以下状态值之一:
状态描述
pending任务已排队,等待开始
in_progress任务正在执行
completed任务成功完成
failed任务遇到错误
cancelled任务被用户取消

选项 B:WebSocket(实时进度)

用于实时进度更新并收集输出元数据:
详细的消息类型和二进制预览图像处理请参阅 WebSocket 参考

步骤 3:下载输出

任务完成后,下载生成的文件。从 WebSocket 返回的 outputs 对象(或通过历史端点获取)包含按节点 ID 组织的输出数据。每个节点的输出可能包含 imagesvideoaudio 数组,其中包含文件元数据。 输出结构示例:
节点 ID(此例中的 "9")对应于工作流中的 SaveImage 或其他输出节点。您可以通过打开工作流 JSON 文件并查找 class_typeSaveImageVHS_VideoCombine 等的节点来找到这些 ID。
/api/view 端点返回 302 重定向到临时签名 URL。您的 HTTP 客户端必须跟随重定向才能下载文件。

完整示例

以下是结合所有三个步骤的完整端到端示例:

可用端点

类别描述
工作流提交工作流、检查状态
任务监控任务状态和队列
输入上传图像、遮罩和其他输入
输出下载生成的内容
WebSocket实时进度更新
对象信息可用节点及其定义

后续步骤

上面的快速入门涵盖了提交工作流和获取结果的基础知识。对于更高级的用例,请参阅 Cloud API 参考
  • 上传输入文件 - 为需要外部输入的工作流上传图像、遮罩或其他用户提供的内容
  • 修改工作流输入 - 在提交前动态更改工作流参数,如提示词、随机种子或节点设置
  • 使用合作伙伴节点 - 调用需要额外 API 密钥配置的外部 AI 服务(Flux Pro、Ideogram 等)
  • 队列管理 - 监控队列状态、取消任务或中断正在运行的执行
  • 错误处理 - 处理 HTTP 错误、执行失败,并了解异常类型
其他资源: