> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comfy.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy API v2 概览

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

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

大多数人应该从 [Comfy SDK](/zh/development/api-development/sdks) 开始，这些 SDK 使用 Python 和 TypeScript 封装了此 API。如果您使用其他语言，可以直接调用这些端点。

## 设计原则

* **优先轮询。** 每项能力都可以通过简单的 GET 轮询访问。SSE 流是实时增强，绝不是事实来源。
* **一切皆可恢复。** 提交是幂等的，在 `expires_at` 之前，任务状态和输出均可通过 ID 检索。
* **内容寻址资产。** 资产是基于内容寻址 blob 的 UUID 标识记录，blob 以服务器计算的 blake3 哈希为键，因此相同的输入不会被重复上传。
* **跟随链接，不要自行构造 URL。** 响应中嵌入了后续 URL。

想了解这些设计背后的原因，请参阅 [设计说明](/zh/development/api-development/sdks-design)。

## 基础 URL

| 环境                                                                     | URL                       | 身份验证                              |
| ---------------------------------------------------------------------- | ------------------------- | --------------------------------- |
| Comfy Cloud                                                            | `https://cloud.comfy.org` | `Authorization: Bearer <api-key>` |
| 自托管，通过 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy) | `http://127.0.0.1:8189`   | 默认无认证，可选静态 bearer 令牌              |

## 端点分类

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