> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-willie-des-1087-router-migration-block.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy API: 서버리스 배포

> 버전 관리되는 ComfyUI 환경을 빌드하고, 관리형 엔드포인트로 배포한 뒤 API를 통해 워크플로를 실행합니다.

<Warning>
  Comfy API 배포는 베타 버전입니다. [platform.comfy.org](https://platform.comfy.org)에서 가입하여 액세스를 신청하세요.
</Warning>

Comfy API를 사용하면 ComfyUI 워크플로를 온디맨드 GPU 용량을 갖춘 관리형 자동 확장 엔드포인트로 배포할 수 있습니다. **Build**는 버전 관리형 ComfyUI 환경의 정의로, 로컬 설치에서 가져온 모델, 커스텀 노드, 설정을 담고 있습니다. Build and Deploy CLI는 Build 정의를 프로젝트 안에 보관하고, 그 정의로부터 릴리스를 생성하며, 트래픽을 처리할 준비가 되면 릴리스를 배포합니다.

<CardGroup cols={2}>
  <Card title="1. 빌드(Build)" icon="box">
    로컬 ComfyUI 설치로부터 빌드 정의를 생성합니다.
  </Card>

  <Card title="2. 릴리스(Release)" icon="tag">
    Build에서 변경 불가능한 Linux/NVIDIA 릴리스를 만듭니다.
  </Card>

  <Card title="3. 배포(Deploy)" icon="cloud-arrow-up">
    릴리스에 URL과 관리형 GPU 용량을 부여합니다.
  </Card>

  <Card title="4. 실행(Run)" icon="code">
    활성 배포에 API 형식 워크플로를 제출합니다.
  </Card>
</CardGroup>

## 빠른 시작

로컬 설치와 API 형식 워크플로가 준비되면 다음 명령을 사용하세요.

compute 출력 결과를 참고해 유효한 리전과 GPU를 선택하세요. 필요하면 `<region>`과 `l4`를 바꿉니다. `deploy up`이 출력하는 배포 ID를 마지막 명령에 복사하세요.

```bash theme={null}
comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes

comfy build push --release --target linux/nvidia
comfy deploy refs compute # get available regions and GPU classes
comfy deploy up --gpu l4 --region <region> --min 1 --max 4 --watch # prints the deployment ID
comfy deploy run --workflow workflow_api.json --deployment <deployment-id> --output-dir ./results
```

<Steps>
  <Step title="초기화">
    ```bash theme={null}
    comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes
    ```
  </Step>

  <Step title="릴리스 생성">
    ```bash theme={null}
    comfy build push --release --target linux/nvidia
    ```

    이 명령은 Build를 동기화하고 지정한 타깃에 대한 릴리스를 생성합니다.
  </Step>

  <Step title="배포 시작">
    사용 가능한 리전과 GPU 클래스를 아직 모른다면 먼저 확인하세요.

    ```bash theme={null}
    comfy deploy refs compute
    ```

    그런 다음 배포를 생성하거나 조정(reconcile)합니다.

    ```bash theme={null}
    comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch
    ```

    `deploy up`은 새 배포 ID를 출력합니다. 나중에 다시 확인해야 한다면 현재 Build의 준비 상태 배포를 나열하세요.

    ```bash theme={null}
    comfy deploy ls --status ready
    ```

    반환된 `dep_...` 값을 `--deployment`에 사용합니다.
  </Step>

  <Step title="워크플로 실행">
    ```bash theme={null}
    comfy deploy run \
      --workflow workflow_api.json \
      --deployment <deployment-id> \
      --output-dir ./results
    ```

    CLI가 API 형식 워크플로를 제출하고 그 출력을 `./results`에 다운로드합니다.
  </Step>
</Steps>

## 빌드 파일

`comfy-build.yaml`은 Build의 로컬 원본 정보(source of truth)입니다. 빌드 정의와 마지막으로 확인한 원격 상태를 저장하므로, CLI가 올바른 Build를 자동으로 선택하고 로컬 변경이 더 최신의 원격 정의를 덮어쓰기 전에 경고할 수 있습니다.

이 파일은 프로젝트와 함께 보관하세요. 이 파일은 Build를 설명할 뿐, 모델 바이트 자체는 담고 있지 않습니다.

## 1. Build 초기화

로컬 ComfyUI 설치에서 시작합니다. 이 명령은 모델과 커스텀 노드를 스캔한 뒤 `comfy-build.yaml`을 작성합니다.

```bash theme={null}
comfy build init --name "my-comfy-build" --models-dir ./models --custom-nodes-dir ./custom_nodes
```

푸시하기 전에 로컬 사양이 설치본 및 원격 Build와 어떻게 다른지 확인하세요.

```bash theme={null}
comfy build status
```

## 2. 업데이트와 릴리스

로컬 ComfyUI 설치를 변경한 후 로컬 빌드 정의를 새로 고칩니다.

```bash theme={null}
comfy build update --yes
```

빠른 방법으로, 한 번의 명령으로 정의를 푸시하고 타깃에 대해 릴리스할 수 있습니다.

```bash theme={null}
comfy build push --release --target linux/nvidia
```

기존 Build에서 또 다른 릴리스를 만들어야 한다면, 지원되는 타깃을 확인한 뒤 명시적으로 릴리스를 생성하세요.

```bash theme={null}
comfy build refs build-targets
comfy build release create --target linux/nvidia --watch
```

특정 릴리스의 빌드 로그를 따라가려면 다음을 사용합니다.

```bash theme={null}
comfy build release logs rel_123456 --target linux/nvidia --follow
```

## 리전과 GPU 가용성

리전 용량은 수시로 변하므로 스크립트에 정적 목록을 복사하지 마세요. 배포 대상을 선택할 때는 플랫폼 카탈로그를 조회하세요:

```bash theme={null}
comfy deploy refs compute
```

결과를 필터링하려면 `--region <region>`을 사용하세요:

```bash theme={null}
comfy deploy refs compute --region <region>
```

반환된 `region`과 `gpu` 쌍을 `comfy deploy up`에 복사하세요:

```bash theme={null}
comfy deploy up --gpu <gpu> --region <region> --min 1 --max 4 --watch
```

배포 시점에 각 리전에서 어떤 GPU 클래스가 사용 가능한지는 이 카탈로그가 기준입니다.

## 3. 릴리스 배포

리전에서 사용 가능한 컴퓨트를 확인한 뒤, 선택한 릴리스에 대한 배포를 생성하거나 조정합니다:

```bash theme={null}
comfy deploy refs compute --region US-MO-2

comfy deploy up \
  --gpu l4 \
  --region US-MO-2 \
  --min 1 \
  --max 4 \
  --watch
```

`--min`과 `--max`는 워커의 최소 및 최대 범위를 설정합니다. 배포 상태, 릴리스 최신 여부, 서빙 활동을 추적하려면 `comfy deploy status --watch`를 사용하세요.

## 4. 워크플로 실행

준비된 배포에 [API 형식 워크플로](/ko/development/api-development/workflow-api-format)를 제출합니다.

```bash theme={null}
comfy deploy run \
  --workflow workflow_api.json \
  --deployment dep_123456 \
  --output-dir ./results
```

`COMFY_BASE_URL`을 배포 URL로 설정하면 [Comfy SDK](/ko/development/api-development/sdks)에서도 이 엔드포인트를 호출할 수 있습니다. SDK 요청에는 여전히 API 키가 필요합니다. [기본 URL 선택](/ko/development/api-development/sdks#기본-url-선택)을 참조하세요.

## 배포 운영

```bash theme={null}
# 워커 수의 상한과 하한 변경
comfy deploy scale --deployment dep_123456 --min 2 --max 5

# 배포 레코드를 유지한 채 일시 중지 또는 재개
comfy deploy stop --deployment dep_123456
comfy deploy start --deployment dep_123456
```

## 검사 및 정리

```bash theme={null}
# Build state
comfy build ls
comfy build show --id bld_123456
comfy build release ls
comfy build release show rel_123456

# Deployment state
comfy deploy ls --workspace --status ready
comfy deploy logs --deployment dep_123456
comfy deploy events --deployment dep_123456
```

<Warning>
  배포 삭제와 Build 삭제는 서로 별개인 되돌릴 수 없는 작업입니다. `comfy deploy delete --yes`나 `comfy build delete --id bld_123456 --yes`를 사용하기 전에 대상을 확인하세요.
</Warning>

## FAQ

<AccordionGroup>
  <Accordion title="Comfy API 배포는 무엇을 제공하나요?">
    Comfy API 배포는 API 형식 워크플로를 실행하기 위한 관리형 자동 확장 엔드포인트입니다. `comfy deploy run` 또는 [Comfy SDK](/ko/development/api-development/sdks)로 워크플로를 제출하세요.
  </Accordion>

  <Accordion title="하나의 Build가 여러 워크플로에서 만들어질 수 있나요?">
    예. Builder에서 하나 이상의 워크플로를 업로드하여 해당 모델과 커스텀 노드를 미리 선택할 수 있습니다. 실행할 모든 워크플로에 필요한 의존성을 포함한 다음, 각 API 형식 워크플로를 배포된 엔드포인트에 제출하세요.

    각 배포는 하나의 GPU 유형을 사용합니다. 서로 다른 GPU 유형에서 워크플로를 실행하려면 동일한 Build로 별도의 배포를 생성하세요.
  </Accordion>

  <Accordion title="배포하지 않은 Build를 저장하는 데에도 비용이 청구되나요?">
    아니요. Build와 해당 릴리스는 계정에 무료로 저장됩니다. 배포하기 전까지는 Build의 저장 공간에 대한 비용이 청구되지 않습니다.

    스토리지 청구는 배포와 함께 시작됩니다.

    * 릴리스를 배포하면 해당 모델이 배포의 워커가 공유하는 네트워크 스토리지에 스테이징됩니다. 이 스토리지는 배포 후 읽기 전용이며, 해당 리전에 Build의 배포가 하나라도 존재하는 동안 GB-월 단위로 청구됩니다. `comfy deploy stop`으로 배포를 일시 중지한 상태도 포함됩니다.
    * 각 워커에는 고정 50 GB 컨테이너 디스크도 할당됩니다. 이 디스크는 임시적이며 워커가 실행되는 동안에만 워커의 컴퓨트 비용의 일부로 청구됩니다.
    * 배포를 삭제하면 해당 컴퓨트가 해제됩니다. 스테이징된 네트워크 스토리지는 해당 리전에서 이를 사용하는 마지막 배포가 삭제된 직후 정리되고, 이에 대한 청구도 종료됩니다.

    현재 스토리지 요금은 [Comfy 가격 페이지](https://www.comfy.org/pricing)를 참조하세요. 컴퓨트 카탈로그(`comfy deploy refs compute`)와 배포 대화 상자에도 배포에 적용되는 요금이 표시됩니다.
  </Accordion>

  <Accordion title="활성 워커는 어떻게 청구되며, 시간당 요금은 얼마인가요?">
    `--min`은 **활성 워커** 수를 설정합니다. 활성 워커는 항상 실행 상태를 유지하여 요청이 콜드 스타트를 기다리지 않도록 하는 워커입니다. 활성 워커는 작업을 처리하는지 여부와 관계없이 실행되는 전체 시간에 대해 초 단위로 청구됩니다.

    `--min`을 초과하고 `--max`까지의 워커는 **flex 워커**입니다. flex 워커는 시작되는 순간부터(시작 및 모델 로딩 포함) 작업 처리까지, 그리고 다시 축소되기 전의 짧은 유휴 창(현재 30초)까지 초 단위로 청구됩니다. flex 워커가 축소되면 비용이 발생하지 않습니다. `--min 0`으로 설정하면 전체 배포가 0으로 축소되어 유휴 상태에서는 컴퓨트 비용이 청구되지 않지만, 첫 번째 요청 시 콜드 스타트 비용이 발생합니다.

    청구는 실행 중인 워커 수를 곱한 실제 초당 워커 사용량을 측정합니다. 워크스페이스의 크레딧이 소진되면 배포가 자동으로 중지됩니다.

    현재 워커당 GPU 요금은 [Comfy 가격 페이지](https://www.comfy.org/pricing)를 참조하세요. 요금은 워커-시간 단위로 책정되며 초 단위로 청구됩니다. 리전별 GPU 가용성은 컴퓨트 카탈로그에서 확인할 수 있습니다. 현재 목록은 `comfy deploy refs compute`를 실행하세요.
  </Accordion>

  <Accordion title="배포는 여러 요청을 어떻게 처리하나요?">
    배포는 요청을 워커 전체에 자동으로 분산하고 구성된 `--min` 및 `--max` 범위 내에서 확장합니다. 즉시 실행할 수 없는 요청은 대기열에 들어가며 워커 용량이 확보되는 대로 처리됩니다.
  </Accordion>

  <Accordion title="프로비저닝에 시간이 오래 걸리면 어떻게 해야 하나요?">
    배포 상태를 확인한 다음, 원인을 파악하기 위해 로그와 이벤트를 살펴보세요.

    ```bash theme={null}
    comfy deploy status --deployment <deployment-id> --watch
    comfy deploy logs --deployment <deployment-id>
    comfy deploy events --deployment <deployment-id>
    ```

    선택한 GPU 또는 리전에 용량이 없으면 나중에 다시 시도하거나 `comfy deploy refs compute`를 실행하여 사용 가능한 리전과 GPU 조합을 선택하세요. 도움을 요청할 때는 Build, 릴리스, 배포 ID를 함께 알려주세요.
  </Accordion>

  <Accordion title="배포를 삭제하면 어떻게 되나요?">
    배포를 삭제하면 해당 엔드포인트가 제거되고 컴퓨트가 해제됩니다. Build나 해당 릴리스는 삭제되지 않습니다. 리전에서 해당 Build를 사용하는 마지막 배포를 삭제하면 스테이징된 네트워크 스토리지가 정리되고 곧 스토리지 청구가 종료됩니다.

    Build 삭제는 별도의 작업입니다. `comfy build delete --id <build-id> --yes`
  </Accordion>
</AccordionGroup>

## 다음 단계

* [Comfy SDK](/ko/development/api-development/sdks)
* [Comfy API v2 개요](/ko/api-reference/v2/overview)
* [워크플로 API 형식](/ko/development/api-development/workflow-api-format)
* [Comfy CLI 레퍼런스](/ko/comfy-cli/reference)