> ## 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.

# Comfy Router에서 자신의 Higgsfield API 키 사용하기

> 자신의 Higgsfield API 키를 Comfy Router에서 사용하세요. 생성 비용은 Comfy 크레딧이 아닌 Higgsfield 계정으로 청구되며, 다른 모든 모델과 동일한 엔드포인트를 통해 이용할 수 있습니다.

Higgsfield는 [API 사용액에 대한 캐시백 프로모션을 진행하고 있습니다](https://higgsfield.ai). 굳이 말리지는 않겠습니다.

Comfy Router에 본인의 Higgsfield 키를 가져오면 생성 작업이 **본인의** Higgsfield 계정에서 실행됩니다. 따라서 그 사용량은 본인의 Higgsfield 사용액으로 집계되며, 그 프로모션이 본인에게 갖는 가치가 무엇이든 그것은 본인의 몫입니다. 또한 Router의 다른 모든 모델과 마찬가지로 하나의 엔드포인트, 하나의 클라이언트, 같은 요청 형태를 그대로 사용합니다.

<Note>
  프로모션과 그 이용약관은 Higgsfield가 소유합니다. 이를 전제로 계획을 세우기 전에 해당 사이트에서 현재 혜택을 확인하세요.
</Note>

## 키를 직접 가져오면 무엇이 달라지나요

| | 내 Comfy 키 | 내 Higgsfield 키 |
| - | - | - |
| 청구 대상 | Comfy 크레딧 | Higgsfield 계정 |
| Comfy 크레딧 차감 | 예 | **없음** |
| 엔드포인트, 요청 본문, 응답 | 동일 | 동일 |

호출에 관한 나머지 모든 것은 동일합니다. 전환을 위해 코드를 변경할 필요는 없습니다. 키를 저장하면 Router가 이를 사용합니다.

<Steps>
  <Step title="Higgsfield API 키 발급받기">
    [Higgsfield 계정](https://higgsfield.ai)에서 키를 생성하세요. 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 키 생성하기">
    이것은 Higgsfield 키와는 별개로, Comfy에 대한 인증에 사용되는 키입니다. [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 등급입니다. 이 모델의 body에는 `cfg_scale`과 `sound` 대신 `resolution`이 포함됩니다. `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의 다른 공급자에 대한 과금 방식은 전혀 달라지지 않습니다.
* 모든 모델의 전체 요청 및 응답 스키마는 [Comfy Router 레퍼런스](/ko/development/comfy-router/reference)에 있습니다.


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