Cloud API 概述

通过编程方式访问 Comfy Cloud，在云端运行工作流、管理文件并监控执行状态

弃用： v1 Cloud API 已弃用，推荐使用 Comfy API v2。它仍可供现有集成使用，也可用于 v2 尚未公开的云端功能，但端点和行为可能会在不另行通知的情况下发生变化。

v1 Cloud API 提供对 Comfy Cloud 的编程式访问，Comfy Cloud 是 Comfy 提供的托管服务，用于在云端基础设施上运行工作流。

Comfy Cloud 是一个有状态应用。你的账户会在任务之间保留状态：积分与订阅等级、已上传的资产和已生成的输出、任务队列，以及已安装的模型和节点集合。v1 API 是整个应用对外暴露的接口，因此它包含可移植的 Comfy API v2 不支持的功能，例如队列管理、模型浏览、节点定义和账户端点。请使用 v2（或封装 v2 的 SDK）提交工作流并获取结果，这种方式同样适用于无服务器部署和自托管的 ComfyUI。对于 v2 之外的云端专属功能，请使用 v1。

要运行工作流，请从 Comfy Cloud 快速入门和 Comfy SDKs 开始。积分和并发限制在 Comfy Cloud 页面中介绍；可运行的 v1 示例位于 Cloud API 参考。本页涵盖 v1 特有的内容：身份验证以及 v2 未公开的端点。

需要订阅： API 访问需要付费的 Comfy Cloud 订阅；免费等级不包含 API 访问权限。请参阅定价页面。

​

基础 URL

https://cloud.comfy.org

这也是 SDK 的默认目标，因此使用 Comfy Cloud 时无需对其进行配置。若要将同一代码指向 Serverless 部署或你自己的 ComfyUI，请设置 COMFY_BASE_URL。请参阅选择基础 URL。

​

身份验证

所有 v1 请求都需要在 X-API-Key 请求头中传递 API 密钥：

curl -X GET "https://cloud.comfy.org/api/user" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY"

请参阅获取 API 密钥了解创建和管理密钥的说明。无效或缺失的密钥会返回 401。密钥关联的订阅未激活时，会返回 429。

同一个密钥也用于合作节点。通过 HTTP 请求时，你需要在 extra_data.api_key_comfy_org 中再次传递该密钥。请参阅使用合作节点查看示例。

​

SDK 尚未覆盖的功能

SDK 覆盖运行工作流、取回结果和取消任务等功能。云端其余功能仅能通过 HTTP 访问，因此即使你使用 SDK 来执行，也需要直接调用这些端点。

功能	端点	参考
队列状态、运行中和待定的任务	GET /api/queue	队列管理
中断当前执行	POST /api/interrupt	队列管理
节点定义和输入规范	GET /api/object_info	对象信息
浏览可用模型	模型端点	Cloud API 参考
账户和用户信息	GET /api/user	Cloud API 参考
引用现有图像的遮罩上传	POST /api/upload/mask	上传输入

两种方式都支持取消任务：SDK 可取消你持有句柄的任务，POST /api/queue 则按 ID 取消。

​

可用端点

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

​

错误处理

REST 端点返回标准 HTTP 状态码：

状态	描述
400	无效请求（工作流错误、字段缺失）
401	未授权（API 密钥无效或缺失）
402	积分不足
429	订阅未激活
500	内部服务器错误

SDK 会改为将这些错误作为类型化异常抛出，包括 Unauthorized、InvalidWorkflow、InsufficientCredits、QueueFull 和 JobFailed，它们都继承自 ComfyError。

执行失败与 HTTP 错误是分开的。有关执行期间传递的 exception_type 值，请参阅错误处理。

​

后续步骤

Comfy Cloud

快速入门、积分和并发限制。

Cloud API 参考

完整的端点文档，包含 curl、Python 和 TypeScript 示例。

Comfy API v2 参考

两个 SDK 底层的版本化 HTTP API。可从任何语言使用。

OpenAPI 规范

用于代码生成的机器可读 API 规范。