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

> 자체 애플리케이션에서 ComfyUI 워크플로를 실행하기 위한 공식 Python 및 TypeScript SDK

<Warning>
  **베타.** SDK 및 SDK가 호출하는 Comfy API v2는 `0.1.x` 버전입니다. API의 형태는 확정되기 전에 변경될 수 있습니다. 지금이 잘못된 점을 알리기에 가장 좋은 시기입니다. [피드백](#feedback)을 참조하세요.
</Warning>

Comfy SDK를 사용하면 애플리케이션에서 ComfyUI 워크플로를 실행하고 결과를 돌려받을 수 있습니다. 워크플로를 제출하면 ComfyUI가 실행하고 출력을 다운로드합니다. 동일한 코드가 Comfy Cloud 또는 직접 호스팅하는 ComfyUI 인스턴스에서 실행됩니다. 기본 URL만 변경됩니다.

SDK는 [Comfy API v2](/ko/api-reference/v2/overview)용 클라이언트입니다. Comfy API v2는 장기적으로 지원하려는 버전 관리되는 HTTP API입니다. ComfyUI의 새 릴리스는 이를 기반으로 구축된 통합을 깨뜨리지 않습니다.

이 방식으로 구축하는 것들:

* Blender나 Krita와 같은 다른 애플리케이션 내부에서 콘텐츠를 생성하는 플러그인
* 사용자를 대신하여 생성 작업을 실행하는 소비자 앱
* 배치 파이프라인, 예를 들어 비디오의 모든 프레임에 워크플로 하나를 실행하는 경우
* 한 번에 많은 워크플로를 동시에 실행해야 하는 백엔드 서비스

<Note>
  이 SDK는 ComfyUI를 **외부에서** 구동합니다. ComfyUI **내부에서** 실행되는 커스텀 노드나 프런트엔드 확장 프로그램을 작성하는 경우에는 [커스텀 노드 개발](/ko/custom-nodes/overview)을 대신 참조하세요. 이들은 별도의 API 집합입니다.
</Note>

## 설치

<CodeGroup>
  ```bash Python theme={null}
  pip install comfy-sdk
  ```

  ```bash TypeScript theme={null}
  npm i @comfyorg/sdk
  ```
</CodeGroup>

Python 3.10 이상. Node 22 이상.

## 빠른 시작

입력 이미지를 업로드하고 워크플로를 실행한 다음 결과를 디스크에 기록합니다.

<CodeGroup>
  ```python Python theme={null}
  from comfy_sdk import Comfy

  # Comfy Cloud
  client = Comfy(api_key="comfyui-...")

  wf = client.workflows.from_file("workflow_api.json")

  asset = client.assets.from_file("photo.png")
  wf.set_input("10", "image", asset)

  job = client.run(wf)
  for output in job.get_outputs("9"):
      output.to_file(output.name)
  ```

  ```typescript TypeScript theme={null}
  import { Comfy } from "@comfyorg/sdk";

  // Comfy Cloud
  const client = new Comfy({ apiKey: "comfyui-..." });

  const wf = await client.workflows.fromFile("workflow_api.json");

  const asset = client.assets.fromFile("photo.png");
  wf.setInput("10", "image", asset);

  const job = await client.run(wf);
  await job.getOutputs("9")[0].toFile("out.png");
  ```
</CodeGroup>

`workflow_api.json`은 [API 형식](/ko/development/api-development/workflow-api-format)으로 저장된 워크플로입니다. `"10"`과 `"9"`는 해당 파일의 노드 ID로, 입력 이미지를 받는 노드와 결과를 가져올 출력 노드를 나타냅니다.

에셋 핸들은 지연 방식으로 동작합니다. `photo.png`는 로컬에서 해시되며 서버에 해당 바이트가 없을 때만 업로드되므로, 동일한 입력으로 다시 실행해도 비용이 들지 않습니다.

`run()`은 작업을 제출하고 터미널 상태에 도달할 때까지 대기합니다. 실행되는 동안 다른 작업을 수행하려면 `submit()`을 대신 사용하고 [이벤트 스트림](#watching-a-job-run)을 확인하세요.

대신 자체 ComfyUI를 대상으로 실행하려면 한 줄을 변경하고 키를 제거하면 됩니다. `Comfy("http://127.0.0.1:8189")`. 아래를 참조하세요.

## 기본 URL 선택

| 연결 대상           | 기본 URL                           | API 키                      |
| --------------- | -------------------------------- | -------------------------- |
| **Comfy Cloud** | `https://cloud.comfy.org` (기본값)  | 필수                         |
| **자체 ComfyUI**  | `http://127.0.0.1:8189` (로컬 프록시) | 기본적으로 없음. 선택적 정적 Bearer 토큰 |

### Comfy Cloud

즉시 사용할 수 있습니다. [API 키](/ko/development/api-development/getting-an-api-key)를 생성하여 클라이언트에 전달하세요.

<Note>
  API 액세스에는 유료 Comfy Cloud 구독이 필요합니다. 무료 티어에는 포함되지 않습니다. 동시에 실행할 수 있는 작업 수는 티어에 따라 다릅니다. [Cloud API 개요](/ko/development/cloud/overview#parallel-execution-concurrent-jobs)를 참조하세요.
</Note>

### 자체 ComfyUI

베타 기간 동안 v2 API는 ComfyUI와 함께 실행되는 작은 오픈소스 서비스인 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy)가 제공합니다:

```bash theme={null}
pip install comfy-api-proxy
comfy-api-proxy
```

기본적으로 `127.0.0.1:8188`에서 실행 중인 ComfyUI를 프록시하고 `127.0.0.1:8189`에서 v2 API를 제공합니다. 둘 중 하나를 변경하려면 `--comfyui`와 `--port`를 사용하세요.

그런 다음 SDK가 `http://127.0.0.1:8189`를 가리키게 하세요. 인증은 기본적으로 필요하지 않습니다. 프록시에 정적 Bearer 토큰을 구성한 경우, 그 토큰을 SDK API 키로 전달하세요: `Comfy("http://127.0.0.1:8189", api_key="...")`. 프록시는 기본적으로 루프백에만 바인딩됩니다. 설치된 ComfyUI에 모델 파일도 업로드하려면 `--comfyui-base-dir /path/to/ComfyUI`와 함께 실행하세요.

프록시는 임시 방편입니다. v2 API가 안정화되면 ComfyUI 코어로 이동하므로 프록시가 더 이상 필요하지 않습니다.

## 작업 실행 보기

`job.events()`는 작업 상태의 라이브 스트림을 제공합니다. 노드와 단계 진행 상황, 미리보기 프레임, 그리고 각 출력이 커밋되는 순간을 보여줍니다. 연결이 끊어지면 자동으로 다시 연결됩니다.

<CodeGroup>
  ```python Python theme={null}
  from comfy_sdk import Progress, Preview, OutputReady, StatusChange

  job = client.submit(wf)

  for event in job.events():
      match event:
          case Progress() as p:
              print(f"{p.value:.0%} {p.message}")
          case Preview() as pv:
              image = pv.to_pil()
          case OutputReady() as o:
              o.output.to_file(f"partial/{o.output.name}")
          case StatusChange(status="succeeded"):
              break

  result = job.result()
  ```

  ```typescript TypeScript theme={null}
  const job = await client.submit(wf);

  for await (const event of job.events()) {
    switch (event.kind) {
      case "progress":
        console.log(event.value);
        break;
      case "outputReady":
        await event.output.toFile(`${event.output.name}`);
        break;
      case "statusChange":
        if (event.status === "succeeded") break;
    }
  }
  ```
</CodeGroup>

`Preview.to_pil()`에는 선택적 Pillow extra가 필요합니다: `pip install "comfy-sdk[pil]"`.

`result()`는 완료된 작업을 반환하거나, 실행이 실패한 경우 노드 수준의 세부 정보와 함께 `JobFailed`를 발생시킵니다. 전체 이벤트 카탈로그는 해당 언어의 [SDK README](#reference)를 참조하세요.

스트림은 재생 가능한 로그가 아니라 실시간 피드입니다. 결과를 위해 의존할 수 있도록 존재하는 것이 아니라, 진행 상황을 표시하기 위해 존재합니다. 작업을 폴링하는 것이 가장 신뢰할 수 있는 정보이며, `run()`, `wait()`, `result()`는 자동으로 폴링을 사용합니다. 그 이유는 [설계 노트](/ko/development/api-development/sdks-design#poll-first-stream-for-progress)를 참조하세요.

## 현재 SDK가 다루는 범위

첫 번째 버전은 한 가지 작업을 제대로 수행합니다. 워크플로를 실행하고 결과를 돌려받는 것입니다.

* **에셋.** 파일, 바이트, 스트림 또는 URL에서 입력 핸들을 생성합니다. 핸들은 지연(lazy) 방식이며 콘텐츠 주소 기반이므로 동일한 입력으로 다시 실행해도 다시 업로드되지 않습니다.
* **제출.** API 형식의 그래프를 제출합니다. 제출은 멱등적이며, 실행 대기열이 가득 찬 경우 제한된 예산 내에서 자동으로 재시도됩니다.
* **실행.** `wait()`으로 폴링하거나 `events()`를 통해 실시간 진행 상황을 추적합니다.
* **출력.** 디스크에 쓰거나, 메모리에 버퍼링하거나, 바이트 범위를 가져오거나, 단기 다운로드 URL을 받을 수 있습니다.
* **오류.** 원시 상태 코드 대신 `JobFailed`, `Unauthorized`, `InsufficientCredits`, `QueueFull`과 같은 타입화된 예외를 제공합니다.
* **취소.** 실행 중인 작업을 취소할 수 있습니다. TypeScript는 추가로 모든 호출에서 `AbortSignal`을 허용합니다.

Python은 동일한 API 표면(surface)을 가진 동기식 `Comfy` 클라이언트와 `AsyncComfy` 클라이언트를 모두 제공합니다. TypeScript는 비동기 전용입니다.

이 버전에는 포함되지 않는 것: 저장된 워크플로 관리, 모델 라이브러리, 노드 인트로스펙션, 명명된 워크플로 파라미터. [설계 노트](/ko/development/api-development/sdks-design#scope-of-the-first-version)에서 API 표면이 이렇게 작게 시작하는 이유를 설명합니다.

## 참조

SDK README는 각 언어에 대한 전체 참조 자료로, 인증, 에셋, 오류 및 저수준 이스케이프 해치를 포함합니다.

<CardGroup cols={2}>
  <Card title="Python SDK" icon="python" href="https://github.com/Comfy-Org/comfy-python-sdk">
    <code>comfy-sdk</code> on PyPI. 동기 및 비동기 클라이언트를 제공합니다.
  </Card>

  <Card title="TypeScript SDK" icon="js" href="https://github.com/Comfy-Org/comfy-typescript-sdk">
    <code>@comfyorg/sdk</code> on npm. 타입 기반 비동기 클라이언트와 저수준 클라이언트를 갖추고 있습니다.
  </Card>

  <Card title="Comfy API v2 참조" icon="code" href="/ko/api-reference/v2/overview">
    두 SDK의 기반이 되는 HTTP API입니다. 어떤 언어에서든 직접 사용할 수 있습니다.
  </Card>

  <Card title="설계 노트" icon="compass" href="/ko/development/api-development/sdks-design">
    이 API가 존재하는 이유, 기존 ComfyUI API와의 관계, 그리고 향후 계획을 설명합니다.
  </Card>
</CardGroup>

## 피드백

`0.1.x`는 의도적인 버전입니다. 메서드 이름, 클라이언트 형태, 이벤트 카탈로그, 오류 분류 체계, 그리고 실제로 에셋 처리가 어떻게 느껴지는지는 모두 아직 변경 비용이 낮으며, 앞으로 몇 주 안에 API 표면을 확정할 계획입니다. 그 이후에는 "장기 지원"이라는 말이 더 이상 여러분을 위해 수정해 드릴 수 없다는 의미가 됩니다.

그러니 무엇이 어색한지, 무엇을 기대했는데 찾지 못했는지, 그리고 결국 어떻게 우회해서 해결했는지 알려주세요. 그런 피드백을 보내실 곳은 [저희 Discord](https://discord.com/invite/comfyorg)의 `#developer-platform` 채널입니다.

다른 언어로 된 퍼스트파티 SDK를 원하신다면 그곳에서 말씀해 주세요. 두 SDK 모두 동일한 문서화된 HTTP 계약을 기반으로 하므로 어떤 언어든 오늘날 API와 통신할 수 있지만, 저희는 수요가 어디에 있는지 알고 싶습니다.