ComfyPilotComfyPilot
文档 / 接口 / Comfy API v2 概览

Comfy API v2 概览

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

接口 overview 更新于 2026-11-12

查看官方原文

Comfy API v2 概览

官方 Comfy API v2 参考：从外部应用上传输入、提交工作流任务并轮询获取结果，在 ComfyUI 中运行工作流。
[!NOTE] Comfy API v2 是有版本管理的 API。v2 内的变更仅作增量扩展；不兼容的变更会在 v3 中发布。

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

大多数人应该从 Comfy SDK 开始，这些 SDK 使用 Python 和 TypeScript 封装了此 API。如果您使用其他语言，可以直接调用这些端点。完整的端点文档位于本节的 API 参考页面中，由 OpenAPI 规范生成。

v2 在哪里运行

同一个 API 由三种形态提供，因此只需更改基础 URL，同一份集成即可在它们之间迁移。

Comfy Cloud。 位于 https://cloud.comfy.org 的托管多租户服务。创建 API 密钥 后即可提交任何工作流。积分、模型浏览和队列管理等 Cloud 特有功能位于 v1 Cloud API，而不在 v2 上。

Comfy API 部署。 通过开发者平台部署的环境会获得位于 https://{deployment}.run.comfy.app 的专属端点，它提供相同的 v2 API 和相同的 API 密钥。Comfy API 部署会针对一个固定环境运行工作流，因此可以独立扩缩，并且 GET /workflow 会返回实际执行的图。构建与部署请参见 Comfy API 部署指南。

开源 ComfyUI，通过代理。 自托管的 ComfyUI 通过 comfy-api-proxy 来使用 v2 协议，这是一个与它一起运行的小型开源服务：

pip install comfy-api-proxy
comfy-api-proxy

默认情况下，它代理 127.0.0.1:8188 上的 ComfyUI，并在 127.0.0.1:8189 上提供 v2 API，仅绑定到回环地址。默认关闭身份验证，可选择使用静态 bearer 令牌。配置细节请参见 SDK 指南中的您自己的 ComfyUI。

设计原则

  • 优先轮询。 每项能力都可以通过简单的 GET 轮询访问。SSE 流只是实时增强，绝不是事实来源。
  • 一切皆可恢复。 提交是幂等的，在 expires_at 之前，任务状态和输出均可通过 ID 检索。而你拿到的输出 URL 比这更短命：请参阅输出 URL 及其有效期。
  • 内容寻址资产。 资产是 UUID 标识的记录，其底层 blob 以服务器计算的 blake3 哈希为键，因此相同的输入不会被上传两次。
  • 跟随链接，不要自行构造 URL。 响应中嵌入了后续要访问的 URL。

想了解这些设计背后的理由，请参阅设计说明。

基础 URL

环境URL身份验证
Comfy Cloudhttps://cloud.comfy.orgAuthorization: Bearer <api-key>
Comfy API 部署https://{deployment}.run.comfy.appAuthorization: Bearer <api-key>
自托管，通过 comfy-api-proxyhttp://127.0.0.1:8189默认无认证，可选静态 bearer 令牌

端点分类

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

输出 URL 及其有效期

有三个不同的生命周期共同决定「我的输出的 URL」，而它们并不是同一个数字。任何向自身用户展示输出的应用都必须为这三者做好规划。

两种 URL 形态

形态获取位置第三方能否打开？有效时长
内容端点，{base}/api/v2/assets/{id}/content任务 outputs 每一项上的 url不能。这是一个需要认证的路由，没有你的 API 密钥会返回 401。稳定。只要该资产存在，它就能解析。
签名存储 URLAsset 响应上的 url、内容端点重定向到的 302 Location，以及两个 SDK 中的 getDownloadUrl()可以。它自带授权信息，因此浏览器或其他服务无需自己的密钥即可读取。较短。目前在 Comfy Cloud 上大约为 6 小时。

实际后果：Output.url 不是一个可分享的链接。把它放进用户浏览器加载的 <img src> 中，他们会收到 401，因为他们的浏览器并不携带你的 API 密钥。签名 URL 才是你可以分发出去的那个。

运行在 comfy-api-proxy 之后的自托管 ComfyUI 完全没有签名 URL。代理从内容端点提供字节流，适用常规认证，SDK 将有效期报告为 null（Python：None）。

读取签名 URL 的有效期

在 Comfy Cloud 和 Comfy API 部署中，签名 URL 生成时的有效期为大约 6 小时。这个数字是服务器端设置，而非 API 契约的一部分，因此请把它当作数量级来对待，绝不要硬编码。请从你获得的响应中读取有效期：

  • Asset 响应上的 url_expires_at 就是同一响应中 url 的真实有效期。
  • getDownloadUrl() 会随 URL 一并返回它，在 TypeScript 中为 expiresAt，在 Python 中为 expires_at。

任务输出上的 url_expires_at 是另一个数字

任务 outputs 某一项上的 url_expires_at 不是签名 URL 的有效期。在 Comfy Cloud 上，它重复的是任务自身的 expires_at，目前等于任务的 created_at 加上固定的 30 天窗口。

该窗口只是一个占位符。平台背后目前还没有任务保留或垃圾回收策略，因此这 30 天只是一个让该字段非空的替代值，并不是关于输出能保持可获取多久的承诺。不要把它当作承诺来理解，也不要据此设置缓存键。如果真正的保留策略取代了它，本页面将会更新。

在自己的产品中展示输出

如果希望在一天之后仍能展示某个输出，请采用以下做法之一：

  • 重新托管字节流。 下载一次输出并将其复制到你自己的存储中。大多数应用最终都会这样做。
  • 按需重新生成。 持久化保存资产的 id，然后在渲染时将其解析为新的 URL（GET /api/v2/assets/{id}，或 getDownloadUrl()），并立即使用该 URL。
  • 代理转发。 从你自己的后端（它已经持有 API 密钥）获取 Output.url，并将字节流传输给你的用户。

行不通的做法是持久化保存签名 URL。它只在数小时内有效，而非数天，因此存储的副本在本地测试期间还能用，但一旦过期就会在你的用户那里失效。

Comfy Router

Comfy API v2 通过提交并轮询的持久任务来运行工作流。如需直接调用模型（单个合作伙伴模型、单个请求、模型的原生输入和输出），请参阅 Comfy Router。请先阅读 Router 限制。