Comfy Router 快速入门

Comfy Router 让您用一个 Comfy API 密钥，通过 https://api.comfy.org 调用合作伙伴模型。将模型的输入发送到 POST /v2/models/{provider}/{model}，然后等待已完成的结果。本示例使用 bfl/flux-2-pro 生成一张图像。

创建 API 密钥

在您的 Comfy 工作区中创建一个密钥。在兼容 Bash 的终端中，设置：

export COMFY_API_KEY="comfyui-..."

请将 API 密钥保存在您的服务器或本地环境中。这些示例面向终端或服务器，而不是浏览器 JavaScript。您的工作区还必须已充值。Comfy Router 每次调用都会扣除积分，因此没有积分余额的工作区在首次实际调用时会被拒绝并返回 402，以及 error_type: insufficient_credits。由于该校验在请求体通过验证之前执行，未充值的账户即使发送了一个在其他方面格式有误的请求也会收到 402，因此请先为工作区充值，而不是去调试一个根本不是问题所在的请求体。在运行示例之前，请先前往工作区账单添加积分。

为本次请求保存一个密钥

为这张图像生成一次该值。如果重试同一个请求，请复用它。

export COMFY_REQUEST_KEY="$(uuidgen)"

如果 uuidgen 不可用，请使用其他 UUID 生成器。开始生成新图像时，请使用新的密钥。

生成一张图像

选择您的语言并运行示例。图像生成可能需要几分钟。

curl --max-time 660 \
  https://api.comfy.org/v2/models/bfl/flux-2-pro \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $COMFY_REQUEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "a red teapot on a windowsill, morning light"}'

# Python 3.10+
# 安装：python -m pip install "comfy-sdk>=0.3.0"
# 保存为 quickstart.py，然后运行：python quickstart.py

import os

from comfy_sdk import Comfy

# Comfy 会从环境中读取 COMFY_API_KEY。
with Comfy() as client:
    result = client.models.run(
        "bfl/flux-2-pro",
        {"prompt": "a red teapot on a windowsill, morning light"},
        idempotency_key=os.environ["COMFY_REQUEST_KEY"],
        timeout=660.0,
    )

print("image:", result["result"]["sample"])

// Node.js 22+
// 安装：npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx
// 保存为 quickstart.mts，然后运行：npx tsx quickstart.mts

import { comfy } from "@comfyorg/sdk";

// Comfy 会从环境中读取 COMFY_API_KEY。
type FluxResult = { result: { sample: string } };
const idempotencyKey = process.env.COMFY_REQUEST_KEY;
if (!idempotencyKey) throw new Error("Set COMFY_REQUEST_KEY first.");

const result = await comfy.models.run<FluxResult>(
  "bfl/flux-2-pro",
  { prompt: "a red teapot on a windowsill, morning light" },
  { idempotencyKey, timeoutMs: 660_000 },
);
// 有些模型会直接返回已生成的文件本身，而不是 JSON。
if (result.kind !== "json") throw new Error("expected a JSON result");

console.log("image:", result.data.result.sample);

// Swift 5.9+（macOS 14+、iOS 17+）。此代码片段是一个命令行程序。
// 不要将密钥打包进 iOS 应用：它可以被从二进制文件中提取出来。
// 在应用中，请调用您自己的后端，并将密钥保存在那里。
// 安装：添加 .package(url: "https://github.com/Comfy-Org/comfy-swift-sdk.git", from: "0.5.0")
// 将 ComfySwiftSDK 添加到您的 target，把这段代码放进 Sources/.../main.swift，然后运行：swift run

import ComfySwiftSDK
import Foundation

let env = ProcessInfo.processInfo.environment

guard let apiKey = env["COMFY_API_KEY"], !apiKey.isEmpty else {
    fatalError("Set COMFY_API_KEY first.")
}
guard let requestKey = env["COMFY_REQUEST_KEY"], !requestKey.isEmpty else {
    fatalError("Set COMFY_REQUEST_KEY first.")
}

let client = ComfyCloudClient(apiKey: apiKey)

let result = try await client.models.run(
    "bfl/flux-2-pro",
    input: ["prompt": "a red teapot on a windowsill, morning light"],
    idempotencyKey: requestKey,
    timeout: 660  // 秒
)

// 有些模型会直接返回已生成的文件本身，而不是 JSON。
guard let sample = result.output["result"]["sample"].stringValue else {
    fatalError("expected a JSON result carrying result.sample")
}

print("image:", sample)

三个示例都从 COMFY_API_KEY 获取密钥：Python 和 TypeScript 客户端会自行从环境中读取它，而 Swift 示例会读取它并将其传给 ComfyCloudClient(apiKey:)。

读取并保存结果

对于该模型，图片网址位于响应体中的 result.sample。简略的响应如下所示；下面的网址仅作示意：

{
  "status": "Ready",
  "result": { "sample": "https://example.com/generated-image.jpeg" }
}

打开返回的网址，或将其下载：

curl --fail --location "PASTE_IMAGE_URL_HERE" --output teapot.jpg

请及时下载。Router 可以将 BFL 资产转存到 Comfy 存储上，但网址会过期，重放并不会为其续期。转存失败可能留下一个有效期更短的提供商网址。参见结果资产。

无需等待，使用队列

run 会保持连接直到图像就绪。若想立即拿回 request_id，并在之后从当前进程或其他进程收集结果，请改为调用 submit（第 3 步安装的 SDK 版本已包含该功能），或通过 HTTP 将相同的请求体发送到 POST /v2/models/{provider}/{model}/requests。调用时请像第 2 步那样一并发送 Idempotency-Key：这样，在连接中断后重试的 submit 会返回原始请求，而不会再次入队并被重复计费。各 SDK 每调用一次 submit 都会生成一个。每个模型页面在同步代码片段旁都有一个 Queue and collect later 标签页，队列投递详细介绍了状态、取消与结果收集。队列投递的作用范围限于你的密钥所对应的工作区，而在你的 Comfy 工作区中创建的密钥会携带该工作区。

选择模型

浏览 Comfy Router 提供的模型，查看它们的输入，然后替换本示例中的模型 ID。

使用 Comfy 开发

运行工作流

Comfy Router

Comfy CLI

规范

Demo Apps

Comfy Router 快速入门

无需等待，使用队列

选择模型

​无需等待，使用队列

​选择模型

无需等待，使用队列

选择模型