v1 Cloud API 概述

已弃用的 v1 Cloud API 范围：认证以及 Comfy API v2 尚未提供的 Cloud 专属端点

[!WARNING] 弃用： v1 Cloud API 已弃用，请改用 Comfy API v2。现有的集成以及 v2 尚未提供的 Cloud 功能仍可继续使用它，但端点和行为可能会在不另行通知的情况下发生变化。

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

Comfy Cloud 是一个有状态的应用。你的账户带有跨任务持续存在的状态：积分和订阅等级、已上传的资产和已生成的输出、任务队列，以及已安装的模型和节点集合。v1 API 是整个应用的对外接口，因此它包含可移植的 Comfy API v2 尚不支持的功能，例如队列管理、模型浏览、节点定义和账户端点。若要提交工作流并获取结果，且同时适用于 Comfy API 部署和自托管的 ComfyUI，请使用 v2（或封装它的 SDK）。围绕它的 Cloud 特有功能则使用 v1。

要运行工作流，请从 Comfy Cloud 快速开始和 Comfy SDKs 入手。积分和并发限制请参见用量与限制；可运行的 v1 示例位于 Cloud API 参考。本页涵盖 v1 特有的接口：身份验证以及 v2 未公开的端点。

[!NOTE] 需要订阅： API 访问需要付费的 Comfy Cloud 订阅；免费套餐不包含该权限。请参阅定价页面。

基础 URL

https://cloud.comfy.org

身份验证

所有 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`	对象信息
浏览可用模型	模型端点	OpenAPI 规范
账户和用户信息	`GET /api/user`	OpenAPI 规范
引用现有图像的遮罩上传	`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 值，请参见错误处理。

后续步骤

[card] Comfy Cloud 快速入门使用 Python 或 TypeScript 运行工作流。

[card] 用量与限制查看 Cloud 积分、并发任务和现有 v1 集成。

[card] 云端 API 参考完整的端点文档，包含 curl、Python 和 TypeScript 示例。

[card] Comfy API v2 参考两个 SDK 底层使用的带版本 HTTP API。可在任何语言中使用。

[card] OpenAPI 规范用于代码生成的机器可读 API 规范。