> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-docs-robin-i18n-sync.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API 概述

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

<Warning>
  **弃用：** v1 Cloud API 已弃用，推荐使用 [Comfy API v2](/zh/api-reference/v2/overview)。它仍可供现有集成使用，也可用于 v2 尚未公开的云端功能，但端点和行为可能会在不另行通知的情况下发生变化。
</Warning>

v1 Cloud API 提供对 [Comfy Cloud](/zh/development/deploy/cloud) 的编程式访问，Comfy Cloud 是 Comfy 提供的托管服务，用于在云端基础设施上运行工作流。

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

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

<Note>
  **需要订阅：** API 访问需要付费的 Comfy Cloud 订阅；免费等级不包含 API 访问权限。请参阅[定价页面](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)。
</Note>

## 基础 URL

```
https://cloud.comfy.org
```

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

## 身份验证

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

```bash theme={null}
curl -X GET "https://cloud.comfy.org/api/user" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY"
```

请参阅[获取 API 密钥](/zh/development/api-development/getting-an-api-key)了解创建和管理密钥的说明。无效或缺失的密钥会返回 `401`。密钥关联的订阅未激活时，会返回 `429`。

同一个密钥也用于[合作节点](/zh/tutorials/partner-nodes/overview)。通过 HTTP 请求时，你需要在 `extra_data.api_key_comfy_org` 中再次传递该密钥。请参阅[使用合作节点](/zh/development/cloud/api-reference#使用合作节点)查看示例。

## SDK 尚未覆盖的功能

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

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

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

## 可用端点

| 类别                                                              | 描述           |
| --------------------------------------------------------------- | ------------ |
| [工作流](/zh/development/cloud/api-reference#运行工作流)                | 提交工作流，检查状态   |
| [任务](/zh/development/cloud/api-reference#检查任务状态)                | 监控任务状态和队列    |
| [输入](/zh/development/cloud/api-reference#上传输入)                  | 上传图像、遮罩和其他输入 |
| [输出](/zh/development/cloud/api-reference#下载输出)                  | 下载已生成的内容     |
| [WebSocket](/zh/development/cloud/api-reference#实时进度-websocket) | 实时进度更新       |
| [对象信息](/zh/development/cloud/api-reference#对象信息)                | 可用的节点及其定义    |

## 错误处理

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

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

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

执行失败与 HTTP 错误是分开的。有关执行期间传递的 `exception_type` 值，请参阅[错误处理](/zh/development/cloud/api-reference#错误处理)。

## 后续步骤

<CardGroup cols={2}>
  <Card title="Comfy Cloud" icon="cloud" href="/zh/development/deploy/cloud">
    快速入门、积分和并发限制。
  </Card>

  <Card title="Cloud API 参考" icon="book" href="/zh/development/cloud/api-reference">
    完整的端点文档，包含 curl、Python 和 TypeScript 示例。
  </Card>

  <Card title="Comfy API v2 参考" icon="cloud" href="/zh/api-reference/v2/overview">
    两个 SDK 底层的版本化 HTTP API。可从任何语言使用。
  </Card>

  <Card title="OpenAPI 规范" icon="file-code" href="/zh/development/cloud/openapi">
    用于代码生成的机器可读 API 规范。
  </Card>
</CardGroup>