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

Higgsfield is [running a cashback promotion on API spend](https://higgsfield.ai). We are not going to try to talk you out of it.

Bring your own Higgsfield key to Comfy Router and your generations run on **your** Higgsfield account — so they count as your Higgsfield spend, and whatever that promotion is worth to you is yours. You still get one endpoint, one client, and the same request shape as every other model on Router.

<Note>
  Higgsfield owns the promotion and its terms. Check the current offer on their site before you plan around it.
</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 your [Higgsfield account](https://higgsfield.ai). 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).