> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-matt-router-pricing-pika-and-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Router 빠른 시작

> 최신 프런티어 미디어 모델로 몇 분 만에 이미지와 비디오를 생성하세요.

<div className="router-quickstart-marker" />

Comfy Router는 `https://api.comfy.org`에서 호스팅되는 이미지 및 비디오 모델을 위한 단일 API를 제공합니다. [Comfy 워크스페이스](https://platform.comfy.org/profile/api-keys?onboarding=router)에서 API 키를 생성한 다음, 공식 [Python 및 TypeScript SDK](/ko/development/api-development/sdks)나 일반 HTTP로 모든 모델을 호출하세요. 과금은 사용량 기반입니다. 각 요청은 구독 없이 워크스페이스 잔액에서 크레딧을 차감합니다.

<Note>
  **Higgsfield를 사용 중이신가요?** 자체 Higgsfield 키를 저장하면 해당 생성은 Comfy 크레딧 대신 Higgsfield 계정으로 청구됩니다. 엔드포인트와 요청 본문은 동일합니다. [자체 키로 Higgsfield 사용하기](/ko/development/comfy-router/higgsfield-byok)를 참고하세요.
</Note>

<Note>
  **LiteLLM으로 지출을 추적하시나요?** Router는 동기 실행의 USD 비용을 LiteLLM이 읽는 헤더에 보고하므로, 가격표를 직접 관리할 필요가 없습니다. [LiteLLM과 함께 Comfy Router 사용하기](/ko/development/comfy-router/litellm)를 참고하세요.
</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 제출 호출은 멱등성 키를 생성하고 자동 재시도에 재사용합니다.
    cURL 예제는 `uuidgen`으로 키를 생성합니다. 사용할 수 없다면 다른 UUID 생성기를 사용하세요.
    상태, 취소, 결과 수집에 대한 세부 정보는 [대기열 전달](/ko/development/comfy-router/queue)을 참고하세요.
  </Step>
</Steps>

## 이미지 기반 비디오 생성 및 레퍼런스 기반 비디오 생성

동일한 Seedance 요청이 이미지, 비디오, 오디오 입력을 받습니다. `content`에 항목을 추가하고 각 항목의 `role`을 설정하세요. 전송하는 역할이 Router가 실행할 작업을 결정합니다. 과금은 역할이 아니라 `content`에 담긴 미디어 종류를 따릅니다. 비디오 입력이 하나라도 있는 요청은 비디오 기반 비디오 생성으로 청구되고, 그런 입력이 없으면서 이미지가 하나라도 있으면 이미지 기반 비디오 생성으로 청구되며, 텍스트만 있는 요청은 텍스트 기반 비디오 생성으로 청구됩니다. 일부 모델은 텍스트 기반 비디오 생성과 이미지 기반 비디오 생성에 동일한 요금을 부과합니다.

| 작업 | `content` 항목 |
| - | - |
| 텍스트 기반 비디오 생성 | `text` 항목 하나 |
| 이미지 기반 비디오 생성 | `text` 항목 하나와 `role: first_frame`인 `image_url` 항목 |
| 첫 프레임과 마지막 프레임 | 위 항목에 더해 `role: last_frame`인 두 번째 `image_url` 항목 |
| 레퍼런스 기반 비디오 생성 | `text` 항목 하나와 `role: reference_image`인 `image_url` 항목들, 그리고 Seedance 2.0 및 2.5에서는 `role: reference_video`인 `video_url` 항목들과 `role: reference_audio`인 `audio_url` 항목들 |

이미지 `url`은 공개 URL이거나 `data:image/<format>;base64,<content>` 문자열일 수 있습니다. 제출, 폴링, 수집은 위 퀵스타트와 정확히 동일합니다. 본문만 달라집니다.

```bash Image-to-video theme={null}
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": [
      {"type": "text", "text": "The fox turns and runs into the trees"},
      {"type": "image_url", "image_url": {"url": "https://example.com/fox.png"}, "role": "first_frame"}
    ],
    "duration": 5,
    "resolution": "720p"
  }'
```

```bash Reference-to-video theme={null}
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": [
      {"type": "text", "text": "The character from the reference walks through a neon-lit market"},
      {"type": "image_url", "image_url": {"url": "https://example.com/character.png"}, "role": "reference_image"},
      {"type": "image_url", "image_url": {"url": "https://example.com/outfit.png"}, "role": "reference_image"}
    ],
    "duration": 5,
    "ratio": "16:9",
    "resolution": "720p"
  }'
```

Seedance 2.5에서 첫 프레임 요청과 첫 프레임 및 마지막 프레임 요청은 첫 프레임에서 출력 화면 비율을 가져옵니다. 구체적인 비율을 지정하면 `400`으로 거부되므로 `ratio`를 생략하거나 `adaptive`를 전송하세요. 요청 스키마는 Seedance 제품군 전체가 공유하며 모델이 무시하는 역할도 나열할 수 있으므로, 각 모델의 [입력 스키마](/ko/development/comfy-router/models)에서 `x-comfy-router-input-modalities` 필드를 확인해 해당 모델이 허용하는 입력 종류를 파악하세요. 예를 들어 `reference_video`와 `reference_audio`는 여기에 `video` 또는 `audio`를 나열하는 모델이 필요합니다.

## 다음 단계

<CardGroup cols={2}>
  <Card title="모델 찾아보기" icon="grid-2" href="/ko/development/comfy-router/models">
    사용 가능한 모델을 살펴보고 모델별 요청 예제를 확인해 보세요.
  </Card>

  <Card title="Router API 사용하기" icon="code" href="/ko/development/comfy-router/api">
    모델 탐색, 스키마, 대기 중인 요청, 오류, 과금에 대해 알아보세요.
  </Card>
</CardGroup>


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