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

# Comfy SDKs

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

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

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

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

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

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

<Note>
  这些 SDK 是从**外部**驱动 ComfyUI。如果您要编写在 ComfyUI **内部**运行的自定义节点或前端扩展，请改用[开发自定义节点](/zh/custom-nodes/overview)。那是一套独立的 API。
</Note>

## 安装

<CodeGroup>
  ```bash Python theme={null}
  pip install comfy-sdk
  ```

  ```bash TypeScript theme={null}
  npm i @comfyorg/sdk
  ```
</CodeGroup>

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

## 快速入门

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

<CodeGroup>
  ```python Python theme={null}
  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)
  ```

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

  // Comfy Cloud
  const client = new Comfy({ apiKey: "comfyui-..." });

  const wf = await client.workflows.fromFile("workflow_api.json");

  const asset = client.assets.fromFile("photo.png");
  wf.setInput("10", "image", asset);

  const job = await client.run(wf);
  await job.getOutputs("9")[0].toFile("out.png");
  ```
</CodeGroup>

`workflow_api.json` 是以 [API 格式](/zh/development/api-development/workflow-api-format) 保存的工作流。`"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` 环境变量，而不是构造函数参数：

```bash theme={null}
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。因此客户端本身在所有环境下都是相同的：

<CodeGroup>
  ```python Python theme={null}
  client = Comfy(api_key="comfyui-...")
  ```

  ```typescript TypeScript theme={null}
  const client = new Comfy({ apiKey: "comfyui-..." });
  ```
</CodeGroup>

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

### Comfy Cloud

开箱即用。创建 [API 密钥](/zh/development/api-development/getting-an-api-key) 并将其传递给客户端。

<Note>
  API 访问需要付费的 Comfy Cloud 订阅。免费版不包含此权限。一次可执行的任务数取决于您的层级。请参阅 [Cloud API 概览](/zh/development/cloud/overview#并行执行（并发任务）)。
</Note>

### Serverless 部署

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

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

### 您自己的 ComfyUI

在测试版期间，v2 API 由 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy) 提供，这是一个与您的 ComfyUI 一起运行的小型开源服务：

```bash theme={null}
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()` 提供任务状态的实时流：节点和步骤进度、预览帧，以及每个输出在提交时的即时信息。如果连接中断，它会自动重新连接。

<CodeGroup>
  ```python Python theme={null}
  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()
  ```

  ```typescript TypeScript theme={null}
  const job = await client.submit(wf);

  // The label is required: a bare `break` inside a switch leaves the switch,
  // not the loop.
  eventLoop: for await (const event of job.events()) {
    switch (event.kind) {
      case "progress":
        console.log(event.value);
        break;
      case "outputReady":
        await event.output.toFile(`${event.output.name}`);
        break;
      case "statusChange":
        if (event.status === "succeeded") break eventLoop;
    }
  }
  ```
</CodeGroup>

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

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

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

## 将输出回溯到其工作流

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

<CodeGroup>
  ```python Python theme={null}
  output = job.outputs[0]
  output.job_id          # the job that produced this file
  ```

  ```typescript TypeScript theme={null}
  const output = job.outputs[0];
  output.jobId; // the job that produced this file
  ```
</CodeGroup>

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

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

<CodeGroup>
  ```python Python theme={null}
  wf = job.get_workflow()

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

  ```typescript TypeScript theme={null}
  const wf = await job.getWorkflow();

  if (wf.format === "save") {
    // the workflow as authored, canvas layout and Note nodes intact
  } else {
    // the executed API-format graph
  }
  ```
</CodeGroup>

**始终根据 `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 仅支持异步。

此版本不包含：管理已保存的工作流、模型库、节点内省，以及命名工作流参数。[设计说明](/zh/development/api-development/sdks-design#首个版本的范围) 解释了为何接口从如此小的范围起步。

## 参考

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

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="https://github.com/Comfy-Org/comfy-python-sdk">
    <code>comfy-sdk</code> 位于 PyPI。提供同步和异步客户端。
  </Card>

  <Card title="TypeScript SDK" icon="js" href="https://github.com/Comfy-Org/comfy-typescript-sdk">
    <code>@comfyorg/sdk</code> 位于 npm。带类型、异步，并提供低层客户端。
  </Card>

  <Card title="Comfy API v2 参考" icon="code" href="/zh/api-reference/v2/overview">
    两个 SDK 底层的 HTTP API。任何语言都可以直接使用。
  </Card>

  <Card title="设计说明" icon="compass" href="/zh/development/api-development/sdks-design">
    这个 API 存在的原因、它与现有 ComfyUI API 的关系，以及未来的发展方向。
  </Card>
</CardGroup>

## 反馈

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

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

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