Comfy SDKs

用于在您自己的应用程序中运行 ComfyUI 工作流的官方 Python 和 TypeScript SDK

测试版。 这些 SDK 及其调用的 Comfy API v2 目前均为 0.1.x 版本。在我们将其锁定之前，API 的结构仍可能发生变化。现在告诉我们哪里有问题，成本最低。参见反馈。

Comfy SDK 让您的应用程序能够运行 ComfyUI 工作流并取回结果。您提交工作流，ComfyUI 执行它，然后您下载输出。同一份代码既可用于 Comfy Cloud，也可用于您自行托管的 ComfyUI 实例，只需更改基础 URL。

这些 SDK 是 Comfy API v2 的客户端。Comfy API v2 是一个版本化的 HTTP API，我们计划长期支持。未来发布的 ComfyUI 新版本不会破坏基于该 API 构建的集成。

人们通过这种方式构建的内容：

• 在其他应用程序（如 Blender 或 Krita）内部生成内容的插件
• 代表用户执行生成的面向消费者的应用
• 批处理流水线，例如对视频的每一帧运行同一个工作流
• 需要同时运行大量工作流的后端服务

这些 SDK 是从外部驱动 ComfyUI。如果您要编写在 ComfyUI 内部运行的自定义节点或前端扩展，请改用开发自定义节点。那是一套独立的 API。

​

安装

Python

pip install comfy-sdk

Python 3.10 或更高版本。Node 22 或更高版本。

​

快速入门

上传输入图像，运行工作流，并将结果写入磁盘。

Python

from comfy_sdk import Comfy

# Comfy Cloud
client = Comfy(api_key="comfyui-...")

wf = client.workflows.from_file("workflow_api.json")

asset = client.assets.from_file("photo.png")
wf.set_input("10", "image", asset)

job = client.run(wf)
for output in job.get_outputs("9"):
    output.to_file(output.name)

workflow_api.json 是以 API 格式 保存的工作流。"10" 和 "9" 是该文件中的节点 ID：即输入图像送入的节点，以及你希望获取结果的输出节点。

资产句柄是惰性的。photo.png 会在本地进行哈希计算，仅当服务器尚未拥有这些字节时才会被上传，因此使用相同的输入重新运行不会产生任何成本。

run() 提交任务并等待其达到终端状态。如要在其执行期间进行其他操作，请改用 submit()，并观察 事件流。

若要改为在你自己的 ComfyUI 上运行，请设置 COMFY_BASE_URL 并去掉密钥。请参阅下文。

​

选择基础 URL

使用环境	基础 URL	API 密钥
Comfy Cloud	https://cloud.comfy.org（默认）	必填
Serverless 部署	https://<deployment>.run.comfy.app	必填
您自己的 ComfyUI	http://127.0.0.1:8189（本地代理）	默认无。可选静态 bearer 令牌

基础 URL 来自 COMFY_BASE_URL 环境变量，而不是构造函数参数：

export COMFY_BASE_URL="https://<deployment>.run.comfy.app"  # serverless
export COMFY_BASE_URL="http://127.0.0.1:8189"               # self-hosted proxy

客户端每次构造时都会读取该变量，它必须是 http(s) URL，未设置或为空则默认为 Comfy Cloud。因此客户端本身在所有环境下都是相同的：

Python

client = Comfy(api_key="comfyui-...")

从早期版本升级？Comfy("<url>", "<key>") 现在是设置 COMFY_BASE_URL 后的 Comfy(api_key="<key>")。api_key 是仅限关键字参数，因此旧的位置参数调用会抛出 TypeError，而不会将 URL 静默当作 API 密钥读取。

​

Comfy Cloud

开箱即用。创建 API 密钥 并将其传递给客户端。

API 访问需要付费的 Comfy Cloud 订阅。免费版不包含此权限。一次可执行的任务数取决于您的层级。请参阅 Cloud API 概览。

​

Serverless 部署

通过 开发者平台 部署的工作流会有自己的端点。将 COMFY_BASE_URL 指向该端点并使用您的 API 密钥，与 Comfy Cloud 完全相同。本指南中的所有内容都以相同的方式工作。

Serverless 部署运行一个固定工作流，因此 get_workflow() 返回执行后的图（format: "api"）。

​

您自己的 ComfyUI

在测试版期间，v2 API 由 comfy-api-proxy 提供，这是一个与您的 ComfyUI 一起运行的小型开源服务：

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

默认情况下，它代理 127.0.0.1:8188 上的 ComfyUI，并在 127.0.0.1:8189 上提供 v2 API。使用 --comfyui 和 --port 可更改其中任一配置。

然后设置 COMFY_BASE_URL="http://127.0.0.1:8189"。默认不需要身份验证。如果代理配置了静态 bearer 令牌，请将该令牌作为 SDK 的 API 密钥传入：Comfy(api_key="...")。默认情况下，代理仅绑定到回环地址。如果您还想将模型文件上传到您的安装中，请使用 --comfyui-base-dir /path/to/ComfyUI 运行它。

该代理只是一个权宜之计。一旦 v2 API 稳定下来，它就会移入 ComfyUI 核心，届时就不再需要代理了。

​

查看任务运行

job.events() 提供任务状态的实时流：节点和步骤进度、预览帧，以及每个输出在提交时的即时信息。如果连接中断，它会自动重新连接。

Python

from comfy_sdk import Progress, Preview, OutputReady, StatusChange

job = client.submit(wf)

for event in job.events():
    match event:
        case Progress() as p:
            print(f"{p.value:.0%} {p.message}")
        case Preview() as pv:
            image = pv.to_pil()
        case OutputReady() as o:
            o.output.to_file(f"partial/{o.output.name}")
        case StatusChange(status="succeeded"):
            break

result = job.result()

Preview.to_pil() 需要可选的 Pillow extra：pip install "comfy-sdk[pil]"。

result() 返回已完成的任务，如果执行失败，则抛出带有节点级详细信息的 JobFailed 异常。有关完整的事件目录，请参阅适用于您的语言的 SDK README。

该流是实时馈送，而非可重放的日志。它的存在是为了让您能够呈现进度，而不是依赖它来获取结果。轮询任务才是权威的，run()、wait() 和 result() 会自动回退到轮询。原因请参阅 设计说明。

​

将输出回溯到其工作流

输出带有生成它们的任务的 ID，因此您可以以文件为起点反向追溯，而无需额外维护一张对应表。

Python

output = job.outputs[0]
output.job_id          # the job that produced this file

单独获取的资源也带有相同的 ID，因此您之后找到的文件依然能回溯到生成它的任务。对于您上传的资源，该 ID 为 None（TypeScript 中为 undefined），因为上传的资源没有对应的生成任务。

您可以向任务查询其背后的工作流。即使该任务不是在当前进程中提交的，只要通过 ID 重新加载，同样可以做到：

Python

wf = job.get_workflow()

if wf.format == "save":
    ...  # the workflow as authored, canvas layout and Note nodes intact
else:
    ...  # the executed API-format graph

始终根据 format 进行分支判断。 返回哪种形状取决于任务的提交方式，而不是您在每次请求中能控制的任何因素：

format	您获得的内容	适用情况
save	任务运行时所使用的版本对应的创作工作流，包含画布布局和仅编辑器可见的节点（如 Note）	从 Comfy Cloud 编辑器提交的任务，此类任务会固定工作流版本
api	已执行的图。仅编辑器可见的结构已消失，Get/Set 节点已展开	其他所有情况，包括目前通过这些 SDK 提交的每个任务

您通过 SDK 提交的任务始终返回 api，因为 v2 提交目前还没有版本固定字段。这种情况将来会改变；判别字段的存在就是为了让您的代码无需随之改变。

​

SDK 目前涵盖的内容

第一个版本只做好一件事：运行工作流并取回结果。

• 资产。 从文件、字节、流或 URL 创建输入句柄。句柄是惰性的，并按内容寻址，因此使用相同输入重新运行时不会再次上传。
• 提交。 提交 API 格式的节点图。提交是幂等的，完整的队列会在有限的预算内自动重试。
• 执行。 使用 wait() 轮询，或通过 events() 获取实时进度。
• 输出。 写入磁盘、缓冲到内存、获取字节范围，或获取短期有效的下载 URL。
• 可追溯性。 每个输出都带有生成它的任务的 ID，并且任务可以返回其背后的工作流。
• 删除资产。 通过句柄或 ID 移除你上传的资产。
• 错误。 提供类型化异常，如 JobFailed、Unauthorized、InsufficientCredits 和 QueueFull，而不是原始状态码。
• 取消。 任务可以在运行时取消。TypeScript 还在任何调用上接受 AbortSignal。

Python 同时提供同步的 Comfy 客户端和接口相同的 AsyncComfy 客户端。TypeScript 仅支持异步。

此版本不包含：管理已保存的工作流、模型库、节点内省，以及命名工作流参数。设计说明 解释了为何接口从如此小的范围起步。

​

参考

SDK 的 README 是每种语言的完整参考，涵盖认证、资产、错误处理以及低层逃生通道。

Python SDK

comfy-sdk 位于 PyPI。提供同步和异步客户端。

TypeScript SDK

@comfyorg/sdk 位于 npm。带类型、异步，并提供低层客户端。

Comfy API v2 参考

两个 SDK 底层的 HTTP API。任何语言都可以直接使用。

设计说明

这个 API 存在的原因、它与现有 ComfyUI API 的关系，以及未来的发展方向。

​

反馈

这是特意采用 0.1.x 版本的。方法名称、客户端形状、事件目录、错误分类法，以及资产管理在实际使用中的体验，这些目前都还很容易更改。我们计划在未来几周内将接口锁定下来。之后，“长期支持”就意味着我们无法再为你修复这些问题了。

所以，请告诉我们哪些地方让你觉得别扭、你期望找到却没有找到的功能，以及你最终是如何绕行解决的。我们的 Discord 中的 #developer-platform 通道就是讨论这些的地方。

如果你想要其他语言的第一方 SDK，也可以在那里告诉我们。两个 SDK 都建立在相同的文档化 HTTP 契约上，所以任何语言现在都可以与 API 通信，但我们更希望知道需求在哪里。