> ## 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 上使用你的 Higgsfield API 密钥

> 将你的 Higgsfield API 密钥接入 Comfy Router：生成费用计入你的 Higgsfield 账户，而不是你的 Comfy 积分，并通过与其他所有模型相同的端点调用。

将你自己的 Higgsfield API 密钥接入 Comfy Router。此后，你的 Higgsfield 生成任务将在**你自己的** Higgsfield 账户上运行并计费，而不会扣除你的 Comfy 积分。因此用量会累计到你的账户，并且 Higgsfield 向你提供的任何定价或积分都适用。你依然只需一个端点、一个客户端，请求形状也与 Router 上其他所有模型保持一致。

<Note>
  你 Higgsfield 用量的定价与条款由 Higgsfield 基于你自己的账户设定。当前详情请参见 [Higgsfield](https://cloud.higgsfield.ai)。
</Note>

## 自带密钥后会有哪些变化

|               | 你的 Comfy 密钥 | 你的 Higgsfield 密钥 |
| ------------- | ----------- | ---------------- |
| 计费对象          | 你的 Comfy 积分 | 你的 Higgsfield 账户 |
| 是否扣除 Comfy 积分 | 是           | **不扣**           |
| 端点、请求体、响应     | 相同          | 相同               |

调用在其他方面完全相同。切换时无需修改代码：你只需保存密钥，Router 便会使用它。

<Steps>
  <Step title="获取 Higgsfield API 密钥">
    在 [Higgsfield API 控制台](https://console.higgsfield.ai) 中创建密钥。这是他们的 API 产品（与面向消费者的应用使用不同的登录）。Higgsfield 以 **id 和 secret 对** 的形式发放，Comfy 将其存储为单个字符串 `id:secret`，请保留冒号，不要拆分成两个字段。
  </Step>

  <Step title="在 Comfy 中保存">
    打开 Comfy 档案中的 [**提供商密钥**](https://platform.comfy.org/profile/provider-keys)，选择 **Higgsfield**，然后粘贴 `id:secret` 值。

    你的密钥在静态存储时会加密，保存后 API 永远不会返回它。Router 仅在为你的调用签名时读取它。
  </Step>

  <Step title="创建 Comfy API 密钥">
    这是用于向 Comfy 进行身份验证的密钥，与 Higgsfield 的密钥相互独立。在 [你的 Comfy 工作区](https://platform.comfy.org/profile/api-keys) 中创建它，然后设置：

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

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

  <Step title="运行模型">
    复制并粘贴下方针对你所选模型的代码片段。
  </Step>
</Steps>

## 模型

<Tabs>
  <Tab title="Kling 3.0 std">
    在质量和速度之间取得平衡。`duration` 接受 3–15 秒。

    <CodeGroup>
      ```bash cURL theme={null}
      curl --max-time 660 \
        https://api.comfy.org/v2/models/higgsfield/higgsfield-kling-3-std \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
          "duration": 5,
          "aspect_ratio": "16:9",
          "cfg_scale": 0.5,
          "sound": "on"
        }'
      ```

      ```python Python theme={null}
      # Python 3.10+
      # 安装：python -m pip install "comfy-sdk>=0.3.0"

      from comfy_sdk import Comfy

      # Comfy 会从环境变量中读取 COMFY_API_KEY。
      with Comfy() as client:
          result = client.models.run(
              "higgsfield/higgsfield-kling-3-std",
              {
                  "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
                  "duration": 5,
                  "aspect_ratio": "16:9",
                  "cfg_scale": 0.5,
                  "sound": "on",
              },
              timeout=660.0,
          )

      print("video:", result["video"]["url"])
      ```

      ```typescript TypeScript theme={null}
      // Node.js 22+
      // 安装：npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx

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

      type HiggsfieldResult = { video: { url: string } };

      const { data } = await comfy.models.run<HiggsfieldResult>(
        "higgsfield/higgsfield-kling-3-std",
        {
          prompt: "A cinematic glass pavilion in a misty pine forest at sunrise",
          duration: 5,
          aspect_ratio: "16:9",
          cfg_scale: 0.5,
          sound: "on",
        },
        { timeoutMs: 660_000 },
      );

      console.log("video:", data.video.url);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Kling 3.0 pro">
    保真度高于 `std`，主体相同。`duration` 接受 3–15 秒。

    <CodeGroup>
      ```bash cURL theme={null}
      curl --max-time 660 \
        https://api.comfy.org/v2/models/higgsfield/higgsfield-kling-3-pro \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
          "duration": 5,
          "aspect_ratio": "16:9",
          "cfg_scale": 0.5,
          "sound": "on"
        }'
      ```

      ```python Python theme={null}
      # Python 3.10+
      # 安装：python -m pip install "comfy-sdk>=0.3.0"

      from comfy_sdk import Comfy

      with Comfy() as client:
          result = client.models.run(
              "higgsfield/higgsfield-kling-3-pro",
              {
                  "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
                  "duration": 5,
                  "aspect_ratio": "16:9",
                  "cfg_scale": 0.5,
                  "sound": "on",
              },
              timeout=660.0,
          )

      print("video:", result["video"]["url"])
      ```

      ```typescript TypeScript theme={null}
      // Node.js 22+
      // 安装：npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx

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

      type HiggsfieldResult = { video: { url: string } };

      const { data } = await comfy.models.run<HiggsfieldResult>(
        "higgsfield/higgsfield-kling-3-pro",
        {
          prompt: "A cinematic glass pavilion in a misty pine forest at sunrise",
          duration: 5,
          aspect_ratio: "16:9",
          cfg_scale: 0.5,
          sound: "on",
        },
        { timeoutMs: 660_000 },
      );

      console.log("video:", data.video.url);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Kling 3.0 4K">
    4K 档位，请求体与 `std` 和 `pro` 相同。`duration` 接受 3–15 秒。

    <CodeGroup>
      ```bash cURL theme={null}
      curl --max-time 660 \
        https://api.comfy.org/v2/models/higgsfield/higgsfield-kling-3-4k \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
          "duration": 5,
          "aspect_ratio": "16:9",
          "cfg_scale": 0.5,
          "sound": "on"
        }'
      ```

      ```python Python theme={null}
      # Python 3.10+
      # 安装：python -m pip install "comfy-sdk>=0.3.0"

      from comfy_sdk import Comfy

      with Comfy() as client:
          result = client.models.run(
              "higgsfield/higgsfield-kling-3-4k",
              {
                  "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
                  "duration": 5,
                  "aspect_ratio": "16:9",
                  "cfg_scale": 0.5,
                  "sound": "on",
              },
              timeout=660.0,
          )

      print("video:", result["video"]["url"])
      ```

      ```typescript TypeScript theme={null}
      // Node.js 22+
      // 安装：npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx

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

      type HiggsfieldResult = { video: { url: string } };

      const { data } = await comfy.models.run<HiggsfieldResult>(
        "higgsfield/higgsfield-kling-3-4k",
        {
          prompt: "A cinematic glass pavilion in a misty pine forest at sunrise",
          duration: 5,
          aspect_ratio: "16:9",
          cfg_scale: 0.5,
          sound: "on",
        },
        { timeoutMs: 660_000 },
      );

      console.log("video:", data.video.url);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Kling 3.0 turbo">
    速度最快的 Kling 档位。它的请求体包含 `resolution`，而不是 `cfg_scale` 和 `sound`。`duration` 接受 3–15 秒。

    <CodeGroup>
      ```bash cURL theme={null}
      curl --max-time 660 \
        https://api.comfy.org/v2/models/higgsfield/higgsfield-kling-3-turbo \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
          "duration": 5,
          "aspect_ratio": "16:9",
          "resolution": "720p"
        }'
      ```

      ```python Python theme={null}
      # Python 3.10+
      # 安装：python -m pip install "comfy-sdk>=0.3.0"

      from comfy_sdk import Comfy

      with Comfy() as client:
          result = client.models.run(
              "higgsfield/higgsfield-kling-3-turbo",
              {
                  "prompt": "A cinematic glass pavilion in a misty pine forest at sunrise",
                  "duration": 5,
                  "aspect_ratio": "16:9",
                  "resolution": "720p",
              },
              timeout=660.0,
          )

      print("video:", result["video"]["url"])
      ```

      ```typescript TypeScript theme={null}
      // Node.js 22+
      // 安装：npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx

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

      type HiggsfieldResult = { video: { url: string } };

      const { data } = await comfy.models.run<HiggsfieldResult>(
        "higgsfield/higgsfield-kling-3-turbo",
        {
          prompt: "A cinematic glass pavilion in a misty pine forest at sunrise",
          duration: 5,
          aspect_ratio: "16:9",
          resolution: "720p",
        },
        { timeoutMs: 660_000 },
      );

      console.log("video:", data.video.url);
      ```
    </CodeGroup>
  </Tab>

  <Tab title="Wan 3.0">
    参考生视频：传入参考图像或片段，并描述如何使用它们。`duration` 最长支持 30 秒。

    <CodeGroup>
      ```bash cURL theme={null}
      curl --max-time 660 \
        https://api.comfy.org/v2/models/higgsfield/higgsfield-wan-3 \
        -H "X-API-Key: $COMFY_API_KEY" \
        -H "Content-Type: application/json" \
        -d '{
          "prompt": "Use Image 1 for the character and Video 1 for the camera movement",
          "image_urls": ["https://cdn.example.com/character.jpg"],
          "video_urls": ["https://cdn.example.com/camera-reference.mp4"],
          "duration": 8,
          "resolution": "1080p",
          "aspect_ratio": "adaptive",
          "generate_audio": true
        }'
      ```

      ```python Python theme={null}
      # Python 3.10+
      # 安装：python -m pip install "comfy-sdk>=0.3.0"

      from comfy_sdk import Comfy

      with Comfy() as client:
          result = client.models.run(
              "higgsfield/higgsfield-wan-3",
              {
                  "prompt": "Use Image 1 for the character and Video 1 for the camera movement",
                  "image_urls": ["https://cdn.example.com/character.jpg"],
                  "video_urls": ["https://cdn.example.com/camera-reference.mp4"],
                  "duration": 8,
                  "resolution": "1080p",
                  "aspect_ratio": "adaptive",
                  "generate_audio": True,
              },
              timeout=660.0,
          )

      print("video:", result["video"]["url"])
      ```

      ```typescript TypeScript theme={null}
      // Node.js 22+
      // 安装：npm install "@comfyorg/sdk@>=0.4.0" --save-dev tsx

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

      type HiggsfieldResult = { video: { url: string } };

      const { data } = await comfy.models.run<HiggsfieldResult>(
        "higgsfield/higgsfield-wan-3",
        {
          prompt: "Use Image 1 for the character and Video 1 for the camera movement",
          image_urls: ["https://cdn.example.com/character.jpg"],
          video_urls: ["https://cdn.example.com/camera-reference.mp4"],
          duration: 8,
          resolution: "1080p",
          aspect_ratio: "adaptive",
          generate_audio: true,
        },
        { timeoutMs: 660_000 },
      );

      console.log("video:", data.video.url);
      ```
    </CodeGroup>
  </Tab>
</Tabs>

## 读取结果

`run` 返回 Higgsfield 自身的终端文档。下载 URL 位于 `video.url`：

```json theme={null}
{
  "status": "completed",
  "request_id": "0c4a9e17-5b82-4d66-9a3f-7c1e08b45d29",
  "video": { "url": "https://example.com/generated.mp4" }
}
```

请尽快保存：

```bash theme={null}
curl --fail --location "PASTE_VIDEO_URL_HERE" --output out.mp4
```

Router 会替你轮询 Higgsfield，因此 `queued` 和 `in_progress` 永远不会到达你这里：你拿到的要么是已完成文档，要么是错误。`nsfw`、`failed` 和 `canceled` 属于终端失败状态；`failed` 会在 `error` 中携带详细信息。

## 注意事项

* **验证会在调用 Higgsfield 之前进行。** 超出已发布范围的请求体会返回 `422`，并指明有问题的字段，且不会向任何上游发送内容，因此错误的请求不会给你带来任何损失。
* **你的密钥仅用于你有密钥的模型。** 保存 Higgsfield 密钥不会改变 Router 上任何其他提供商的计费方式。
* 每个模型的完整请求与响应 schema 都在 [Comfy Router 参考](/zh/development/comfy-router/reference) 中。