> ## Documentation Index
> Fetch the complete documentation index at: https://comfyuiwiki.com/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>

<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 的 submit 调用都会创建一个幂等键，并在自动重试时复用它。
    cURL 示例使用 `uuidgen` 创建一个。如果它不可用，请使用其他 UUID 生成器。
    关于状态、取消与结果收集的详情，请参阅[队列投递](/zh/development/comfy-router/queue)。
  </Step>
</Steps>