> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-chore-sync-comfy-api-v2-spec-0ee014e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloud API 概述

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

<Warning>
  **实验性 API：** 此 API 目前处于实验阶段，可能会发生变更。端点、请求/响应格式和行为可能会在不另行通知的情况下进行修改。
</Warning>

# Comfy Cloud API

Comfy Cloud API 提供以编程方式访问 Comfy Cloud 的能力，可在云端基础设施上运行工作流。该 API 与本地 ComfyUI 的 API 兼容，便于迁移现有集成。

如果你使用 Python 或 TypeScript 进行开发，请使用 [Comfy SDKs](/zh/development/api-development/sdks)。这些 SDK 封装了此 API，是运行工作流最快捷的方式。本页介绍 Comfy Cloud 特有的内容：你的 API 密钥、积分和并发限制。其他内容请参阅 [Cloud API 参考](/zh/development/cloud/api-reference)。

<Note>
  **需要订阅：** API 访问权限在 **Standard**、**Creator** 和 **Pro** 等级提供。免费等级不包含 API 访问权限。详情请参阅[定价方案](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)。
</Note>

## 积分与用量

API 请求消耗的是与 Comfy Cloud 网页端相同的月度积分配额：不存在单独的 API 积分池。每个等级的包含积分、加购选项以及单次工作流运行时长上限对 API 任务和网页端任务完全相同。Standard、Creator 和 Pro 等级的月度积分数量请参阅[定价方案](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)。如果月中积分已用完，可在账户仪表盘中购买加购包。

## 基础 URL

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

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

## 身份验证

所有 API 请求都需要 API 密钥。通过原始 HTTP 请求时，请将其放在 `X-API-Key` 请求头中传递。使用 SDK 时，只需将密钥交给客户端一次，客户端会自动为每个请求进行身份验证。

### 获取 API 密钥

请参阅[获取 API 密钥](/zh/development/api-development/getting-an-api-key)了解创建和管理 Cloud API 密钥的说明。

### 使用 API 密钥

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

  ```python Python theme={null}
  import os
  from comfy_sdk import Comfy

  client = Comfy(api_key=os.environ["COMFY_CLOUD_API_KEY"])
  ```

  ```typescript TypeScript theme={null}
  import { Comfy } from "@comfyorg/sdk";

  const client = new Comfy({ apiKey: process.env.COMFY_CLOUD_API_KEY! });
  ```
</CodeGroup>

无效或缺失的密钥会返回 `401`，SDK 会将其作为 `Unauthorized` 抛出。密钥关联的订阅未激活时，会返回 `429`。

同一个密钥也用于[合作节点](/zh/tutorials/partner-nodes/overview)。通过原始 HTTP 请求时，你需要在 `extra_data.api_key_comfy_org` 中再次传递该密钥。使用 SDK 时，当你向 `submit()` 传入 `api_key`，SDK 会自动为你完成。

## 运行工作流

工作流以 [API 格式](/zh/development/api-development/workflow-api-format) 提交，即 ComfyUI 前端的“导出工作流 (API)”选项生成的 JSON。提交工作流后，任务将异步执行，完成后你即可下载输出。

<Card title="Comfy SDKs" icon="code" href="/zh/development/api-development/sdks">
  使用 Python 或 TypeScript 安装、提交工作流、实时跟踪进度并保存输出。从这里开始。
</Card>

如需直接从其他语言调用 HTTP 端点，或使用以下所述功能，请参阅 [Cloud API 参考](/zh/development/cloud/api-reference)。其中介绍了提交、轮询、WebSocket 协议以及输出下载，并附有 curl、Python 和 TypeScript 示例。

### 并行执行（并发任务）

API 用户可以同时提交多个工作流，无需等待上一个任务完成。提交会在任务被接受后立即返回，因此你可以同时保有多个进行中的任务。调度器将并行运行这些任务，最多不超过你订阅套餐所允许的并发数。

| 订阅套餐     | 并发任务 |
| -------- | ---- |
| Standard | 1    |
| Creator  | 3    |
| Pro      | 5    |

超出并发限制提交的任务将正常排队，并在槽位空出后自动执行。如果队列本身已满，SDK 会在有限次数内为你重试，之后才抛出 `QueueFull`。

<Info>
  并行执行目前仅可通过 API 使用。有关订阅详情，请参阅[定价方案](https://www.comfy.org/cloud/pricing?utm_source=docs\&utm_campaign=cloud-api)。
</Info>

## 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 SDKs" icon="code" href="/zh/development/api-development/sdks">
    使用 Python 或 TypeScript 运行工作流。支持资产、实时事件和类型化错误。
  </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>