> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-willie-des-1087-router-migration-block.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# v1 Cloud API 概述

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

<Warning>
  **弃用：** v1 Cloud API 已弃用，请改用 [Comfy API v2](/zh/api-reference/v2/overview)。现有的集成以及 v2 尚未提供的 Cloud 功能仍可继续使用它，但端点和行为可能会在不另行通知的情况下发生变化。
</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) 尚不支持的功能，例如队列管理、模型浏览、节点定义和账户端点。若要提交工作流并获取结果，且同时适用于 Comfy API 部署和自托管的 ComfyUI，请使用 v2（或封装它的 SDK）。围绕它的 Cloud 特有功能则使用 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 订阅；免费等级不包含该权限。请参阅[定价页面](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)。
</Note>

## 基础 URL

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

## 身份验证

所有 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#对象信息) |
| 浏览可用模型          | 模型端点                    | [OpenAPI 规范](/zh/development/cloud/openapi)      |
| 账户和用户信息         | `GET /api/user`         | [OpenAPI 规范](/zh/development/cloud/openapi)      |
| 引用现有图像的遮罩上传     | `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="云端 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>