Comfy Router 快速入门

在几分钟内使用最新前沿媒体模型生成图像和视频。

Comfy Router 为用户提供统一的 API，用于调用托管的图像和视频模型，地址为 https://api.comfy.org。请在你的 Comfy 工作区中创建 API 密钥，然后使用官方 Python 和 TypeScript SDK 或直接通过 HTTP 调用任意模型。计费方式为按使用量付费：默认情况下，每次请求都会从你的工作区余额中扣除积分，无需订阅。费率和其他计费方式请参阅 Router 定价。

[!NOTE] 用 LiteLLM 追踪支出？ Router 会在 LiteLLM 读取的响应头中报告同步运行的美元成本，因此你无需维护价格表。请参阅将 Comfy Router 与 LiteLLM 搭配使用。

1. 创建 API 密钥

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

export COMFY_API_KEY="comfyui-..."

请将 API 密钥保存在你的服务器上或本地环境中。这些示例面向终端或服务器，不适用于浏览器 JavaScript。

Router 按请求扣除积分。如果你的工作区没有积分余额，首次实际调用会返回 402，并带有 error_type: insufficient_credits。该检查在请求体验证之前执行，因此未充值的工作区即使请求无效也可能返回 402。在调试请求体之前，请先到工作区计费添加积分。

2. 将请求加入队列

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

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

import asyncio

from comfy_sdk import AsyncComfy

# AsyncComfy 会从环境变量中读取 COMFY_API_KEY。
async def main():
    async with AsyncComfy() as client:
        handle = await client.models.submit(
            "byteplus/dreamina-seedance-2-5-260628",
            {
                "content": [
                    {
                        "text": "A red fox trotting through a snowy pine forest",
                        "type": "text",
                    },
                ],
                "duration": 5,
                "ratio": "16:9",
                "resolution": "720p",
            },
        )
        print("request_id:", handle.request_id)

        # 轮询直到请求完成，每次等待服务器指定的 Retry-After。
        async for update in handle.iter_events():
            print(update.status, update.queue_position)

        result = await handle.get()

    print("result:", result)

asyncio.run(main())

# 1. 提交请求。保存 201 响应中的 request_id。
curl https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-5-260628/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"content": [{"text": "A red fox trotting through a snowy pine forest", "type": "text"}], "duration": 5, "ratio": "16:9", "resolution": "720p"}'

# 2. 轮询直到状态为 COMPLETED，每次都等待 Retry-After 指定的时长。
REQUEST_ID="paste-request-id-from-201-response"
curl -i "https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-5-260628/requests/$REQUEST_ID/status" \
  -H "X-API-Key: $COMFY_API_KEY"

# 3. 获取模型结果。
curl "https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-5-260628/requests/$REQUEST_ID" \
  -H "X-API-Key: $COMFY_API_KEY"

// 需要 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。
const handle = await comfy.models.submit(
  "byteplus/dreamina-seedance-2-5-260628",
  {
    content: [
      {
        text: "A red fox trotting through a snowy pine forest",
        type: "text",
      },
    ],
    duration: 5,
    ratio: "16:9",
    resolution: "720p",
  },
);
console.log("requestId:", handle.requestId);

// 轮询直到请求完成，每次等待服务器指定的 Retry-After。
for await (const update of handle.events()) {
  console.log(update.status, update.queuePosition);
}

const result = await handle.get();

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

每次 SDK 提交调用都会创建一个幂等键，并在自动重试时复用它。cURL 示例使用 uuidgen 创建一个幂等键。如果该命令不可用，请改用其他 UUID 生成工具。关于状态查询、取消和结果获取的详情，请参阅队列投递。

图生视频与参考生视频

同一个 Seedance 请求可以接受图像、视频和音频输入。向 content 添加条目，并为每个条目设置 role。你发送的 role 决定 Router 执行哪种操作。计费依据 content 中的媒体种类，而不是 role：只要包含视频输入，就按视频到视频计费；否则只要包含图像，就按图生视频计费；只有文本的请求按文生视频计费。有些模型对文生视频和图生视频收取相同的费用。

图像 url 可以是公开 URL，也可以是 data:image/<format>;base64,<content> 字符串。提交、轮询和收集结果的方式与上面的快速上手完全一致，只有请求体不同。

curl https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-5-260628/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {"type": "text", "text": "The fox turns and runs into the trees"},
      {"type": "image_url", "image_url": {"url": "https://example.com/fox.png"}, "role": "first_frame"}
    ],
    "duration": 5,
    "resolution": "720p"
  }'

curl https://api.comfy.org/v2/models/byteplus/dreamina-seedance-2-5-260628/requests \
  -H "X-API-Key: $COMFY_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {"type": "text", "text": "The character from the reference walks through a neon-lit market"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "https://example.com/outfit.png"}, "role": "reference_image"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'

在 Seedance 2.5 上，首帧请求和首尾帧请求会从首帧获取输出的宽高比。请省略 ratio 或传入 adaptive，因为传入具体比例会被拒绝并返回 400。请求 schema 在 Seedance 系列之间共用，可能会列出模型忽略的 role，因此请查看每个模型的输入 schema 中的 x-comfy-router-input-modalities 字段，了解该模型接受哪些输入种类。例如，reference_video 和 reference_audio 需要模型在其中列出 video 或 audio。

下一步

[card] 浏览模型 探索可用的模型，并查找针对具体模型的请求示例。

[card] 使用 Router API 了解模型发现、schema、排队请求、错误以及计费。