> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-matt-router-pricing-pika-and-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Router 快速入门

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

<div className="router-quickstart-marker" />

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

<Note>
  **使用 Higgsfield？** 保存你自己的 Higgsfield 密钥后，这些生成将计入你的 Higgsfield 账户，而不是你的 Comfy 积分。端点相同，请求体也相同。请参阅[使用你自己的密钥的 Higgsfield](/zh/development/comfy-router/higgsfield-byok)。
</Note>

<Note>
  **用 LiteLLM 追踪支出？** Router 会在 LiteLLM 读取的响应头中报告同步运行的美元成本，因此你无需维护价格表。请参阅[将 Comfy Router 与 LiteLLM 搭配使用](/zh/development/comfy-router/litellm)。
</Note>

<Steps titleSize="h2">
  <Step title="创建 API 密钥">
    在[你的 Comfy 工作区](https://platform.comfy.org/profile/api-keys?onboarding=router)中创建密钥。在兼容 Bash 的终端中，设置：

    ```bash theme={null}
    export COMFY_API_KEY="comfyui-..."
    ```

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

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

  <Step title="将请求加入队列">
    选择你的语言并运行示例。生成可能需要几分钟。

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

      ```bash cURL theme={null}
      # 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"
      ```

      ```typescript TypeScript theme={null}
      // 需要 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);
      ```
    </CodeGroup>

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

## 图生视频与参考生视频

同一个 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>` 字符串。提交、轮询和收集结果的方式与上面的快速上手完全一致，只有请求体不同。

```bash Image-to-video theme={null}
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"
  }'
```

```bash Reference-to-video theme={null}
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](/zh/development/comfy-router/models) 中的 `x-comfy-router-input-modalities` 字段，了解该模型接受哪些输入种类。例如，`reference_video` 和 `reference_audio` 需要模型在其中列出 `video` 或 `audio`。

## 下一步

<CardGroup cols={2}>
  <Card title="浏览模型" icon="grid-2" href="/zh/development/comfy-router/models">
    探索可用的模型，并查找针对具体模型的请求示例。
  </Card>

  <Card title="使用 Router API" icon="code" href="/zh/development/comfy-router/api">
    了解模型发现、schema、排队请求、错误以及计费。
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.