> ## 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.

# Comfy API v2 概览

> 官方 Comfy API v2 参考：从外部应用上传输入、提交任务并轮询获取结果，在 ComfyUI 中运行工作流。

<Warning>
  **测试版：** Comfy API v2 目前处于 `0.1.x` 版本，其接口可能仍会发生变化。v2 内部的变更将是增量式的；任何破坏性变更将随 v3 发布。
</Warning>

这是用于从外部应用运行 ComfyUI 工作流的官方、带版本号的 HTTP API：上传输入、提交工作流、观察执行、获取结果。

大多数人应从 [Comfy SDKs](/zh/development/api-development/sdks) 入手，这些 SDK 以 Python 和 TypeScript 封装了此 API。如果您使用其他语言，可以直接调用这些端点。完整的端点文档位于本部分的 API Reference 页面中，这些页面是根据 OpenAPI 规范生成的。

## v2 在哪里运行

同一 API 通过三个入口提供，因此只需更改基础 URL，一个集成即可在它们之间切换。

**Comfy Cloud。** 位于 `https://cloud.comfy.org` 的托管式多租户服务。创建 [API 密钥](/zh/development/api-development/getting-an-api-key) 后，即可提交任意工作流。积分、模型浏览和队列管理等云端专属功能位于 [v1 Cloud API](/zh/development/cloud/overview) 中，而非 v2。

**Serverless API（开发者平台）。** 通过[开发者平台](https://platform.comfy.org)部署的工作流会在 `https://{deployment}.run.comfy.app` 获得专属端点，并使用相同的 API 密钥提供相同的 v2 API。Serverless 部署只运行一个固定的工作流，因此可以独立扩展，且 `GET /workflow` 会返回已执行的工作流图。构建和部署详情请参阅 [Serverless API 指南](/zh/development/serverless/overview)。

**开源 ComfyUI（通过代理）。** 在测试版期间，自托管的 ComfyUI 通过 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy) 以 v2 协议进行通信。这是一个与它一起运行的小型开源服务：

```bash theme={null}
pip install comfy-api-proxy
comfy-api-proxy
```

默认情况下，它代理 `127.0.0.1:8188` 上的 ComfyUI，并在 `127.0.0.1:8189` 上提供 v2 API，且仅绑定到回环地址。默认关闭身份验证，可选静态 Bearer Token。该代理只是一个临时方案：一旦 v2 稳定，它就会移入 ComfyUI 核心，届时不再需要代理。配置详情请参阅 SDK 指南中的[您自己的 ComfyUI](/zh/development/api-development/sdks#您自己的-comfyui)。

## 设计原则

* **轮询优先。** 所有能力均可通过简单的 GET 轮询访问。SSE 流只是实时增强，绝不是事实来源。
* **一切皆可恢复。** 提交是幂等的，任务状态和输出可通过 ID 检索，直到 `expires_at` 为止。
* **内容寻址资产。** 资产是以 UUID 标识的记录，其底层 blob 以服务器计算的 blake3 哈希为键，因此相同的输入不会被重复上传。
* **跟随链接，不要拼接 URL。** 响应中嵌入后续操作的 URL。

有关这些原则背后的理由，请参阅[设计说明](/zh/development/api-development/sdks-design)。

## 基础 URL

| 使用场景                                                                   | URL                                  | 身份验证                              |
| ---------------------------------------------------------------------- | ------------------------------------ | --------------------------------- |
| Comfy Cloud                                                            | `https://cloud.comfy.org`            | `Authorization: Bearer <api-key>` |
| 无服务器部署                                                                 | `https://{deployment}.run.comfy.app` | `Authorization: Bearer <api-key>` |
| 自托管，通过 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy) | `http://127.0.0.1:8189`              | 默认无认证，可选静态 Bearer 令牌              |

## 端点分类

| 类别 | 描述                                  |
| -- | ----------------------------------- |
| 资产 | 基于内容寻址 blob、由 UUID 标识的记录。上传输入，下载输出。 |
| 作业 | 工作流的一次执行。持久、可轮询、可取消。                |

## Comfy Router

Comfy API v2 将工作流作为可提交和轮询的持久任务运行。对于直接模型调用（一个合作伙伴模型、一次请求、模型的原始输入和输出），请参阅 [Comfy Router](/zh/api-reference/comfy-router/quickstart)。请先查阅 [Router 限制](/zh/api-reference/comfy-router/limitations)。Router 尚未正式发布。