> ## Documentation Index
> Fetch the complete documentation index at: https://comfyuiwiki.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Use Your Higgsfield API Key on Comfy Router

> Bring your Higgsfield API key to Comfy Router: generations bill to your Higgsfield account, not your Comfy credits, through the same endpoint as every other model.

Bring your own Higgsfield API key to Comfy Router. Your Higgsfield generations then run on **your** Higgsfield account and bill there, not to your Comfy credits — so the usage accrues to your account, and any pricing or credits Higgsfield offers you apply. You still get one endpoint, one client, and the same request shape as every other model on Router.

<Note>
  Pricing and terms for your Higgsfield usage are set by Higgsfield on your own account. See [Higgsfield](https://cloud.higgsfield.ai) for current details.
</Note>

## What changes when you bring a key

|                                  | Your Comfy Key     | Your Higgsfield Key     |
| -------------------------------- | ------------------ | ----------------------- |
| Billed to                        | Your Comfy credits | Your Higgsfield account |
| Comfy credits charged            | Yes                | **None**                |
| Endpoint, request body, response | Same               | Same                    |

Everything else about the call is identical. You do not change your code to switch — you save a key, and Router uses it.

<Steps>
  <Step title="Get a Higgsfield API key">
    Create a key in the [Higgsfield API console](https://console.higgsfield.ai). This is their API product (a separate login from the consumer app). Higgsfield issues it as an **id and secret pair**, and Comfy stores it as the single string `id:secret` — keep the colon, and do not split it into two fields.
  </Step>

  <Step title="Save it in Comfy">
    Open [**Provider keys**](https://platform.comfy.org/profile/provider-keys) in your Comfy profile, choose **Higgsfield**, and paste the `id:secret` value.

    Your key is encrypted at rest and is never returned by the API once saved. Router reads it only to sign your own calls.
  </Step>

  <Step title="Create a Comfy API key">
    This is the key that authenticates you to Comfy, separate from the Higgsfield one. Create it in [your Comfy workspace](https://platform.comfy.org/profile/api-keys), then set:

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

    Keep API keys on your server or in your local environment. These examples are for a terminal or server, not browser JavaScript.
  </Step>

  <Step title="Run a model">
    Copy and paste a code snippet below for your selected model.
  </Step>
</Steps>

## Models

<Tabs>
  <Tab title="Kling 3.0 std">
    Balanced quality and speed. `duration` accepts 3–15 seconds.

    <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+
      # Install: python -m pip install "comfy-sdk>=0.3.0"

      from comfy_sdk import Comfy

      # Comfy reads COMFY_API_KEY from the environment.
      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+
      // Install: 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">
    Higher fidelity than `std`, same body. `duration` accepts 3–15 seconds.

    <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+
      # Install: 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+
      // Install: 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">
    The 4K tier, same body as `std` and `pro`. `duration` accepts 3–15 seconds.

    <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+
      # Install: 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+
      // Install: 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">
    The fastest Kling tier. Its body carries `resolution` instead of `cfg_scale` and `sound`. `duration` accepts 3–15 seconds.

    <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+
      # Install: 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+
      // Install: 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">
    Reference-to-video: pass reference images or clips and describe how to use them. `duration` accepts up to 30 seconds.

    <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+
      # Install: 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+
      // Install: 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>

## Reading the result

`run` returns Higgsfield's own terminal document. The download URL is at `video.url`:

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

Save it promptly:

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

Router polls Higgsfield for you, so `queued` and `in_progress` never reach you — you get the finished document or an error. `nsfw`, `failed` and `canceled` are the terminal failures; `failed` carries detail in `error`.

## Notes

* **Validation happens before Higgsfield is called.** A body outside the published bounds comes back `422` with the offending field named, and nothing is sent upstream — so a bad request costs you nothing.
* **Your key is used only for models you have a key for.** Saving a Higgsfield key changes nothing about how any other provider on Router is billed.
* Full request and response schemas for every model are in the [Comfy Router reference](/development/comfy-router/reference).