Comfy Router 快速入门

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

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

使用 Higgsfield？ 保存你自己的 Higgsfield 密钥后，这些生成将计入你的 Higgsfield 账户，而不是你的 Comfy 积分。端点相同，请求体也相同。请参阅使用你自己的密钥的 Higgsfield。

用 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

   # 需要 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())
   

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

​

图生视频与参考生视频

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

操作	content 条目
文生视频	一个 text 条目
图生视频	一个 text 条目，加上一个 role: first_frame 的 image_url 条目
首尾帧	上述内容再加上一个 role: last_frame 的 image_url 条目
参考生视频	一个 text 条目，加上若干个 role: reference_image 的 image_url 条目；在 Seedance 2.0 和 2.5 上还包括 role: reference_video 的 video_url 条目和 role: reference_audio 的 audio_url 条目

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

Image-to-video

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"
  }'

Reference-to-video

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。

​

下一步

浏览模型

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

使用 Router API

了解模型发现、schema、排队请求、错误以及计费。