> ## 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 API v2가 만들어진 이유, 기존 ComfyUI API와의 관계, 그리고 앞으로 공개될 기능

[Comfy SDKs](/ko/development/api-development/sdks)와 이 SDK들이 호출하는 [Comfy API v2](/ko/api-reference/v2/overview)에 대한 배경입니다. SDK를 사용하는 데 이 내용이 필요하지는 않습니다. 새 API와 기존 API 중 무엇을 기반으로 구축할지 결정하는 중이라면 이 내용을 읽어 보세요.

## 왜 새로운 API인가

이미 HTTP로 `/prompt`와 `/history`를 호출하여 ComfyUI를 구동할 수 있습니다. 이 엔드포인트들은 ComfyUI 웹 UI를 지원하기 위해 존재하며, 이를 기반으로 구축하는 것은 결코 약속되지 않은 내부 구현에 의존하게 된다는 의미입니다. v2 API는 기존 엔드포인트가 제공할 수 없는 세 가지를 추가합니다.

**약정.** v2는 버전 관리, 문서화, 지원이 보장됩니다. v2 내의 변경 사항은 추가 방식으로만 이루어지며, 호환성을 깨뜨리는 변경 사항은 v3로 출시됩니다. ComfyUI의 새 릴리스는 여러분의 통합을 깨뜨리지 않습니다.

**이식성.** 로컬 ComfyUI, Comfy Cloud, 그리고 나중에 출시하는 다른 모든 제품에서도 동일한 동작을 보장합니다. 동일한 코드, 다른 base URL입니다.

**프로덕션에서도 살아남는 형태.** 지속적인 작업 ID, 멱등적 제출, 유형화된 오류, 정규화된 출력, 실제 배압을 제공합니다. 더 이상 모든 통합이 `prompt_id`와 `/history`를 기반으로 이 다섯 가지를 각자 다시 구현할 필요가 없습니다.

## 기존 엔드포인트를 래핑하지 않는 이유

기존 엔드포인트는 한 번에 하나의 워크플로만 실행하는 단일 ComfyUI 인스턴스를 가정하며, 이러한 가정은 `prompt_id`, `/history`, 웹소켓 프로토콜에 고정되어 있습니다.

v2 API는 그러한 가정을 하지 않습니다. 여러 워크플로가 동시에 실행되고 각각이 영구적인 작업 ID로 식별되는 것이 예외가 아닌 기본 사례입니다.

## 폴링 우선, 진행 상황은 스트리밍으로

v2의 모든 기능은 일반 GET 요청으로 접근할 수 있습니다. `GET /api/v2/jobs/{id}`는 현재 상태, 최신 진행 스냅샷, 지금까지 커밋된 모든 출력을 반환합니다. 이 응답은 작업에 대한 신뢰할 수 있는 기준 정보이며, 작업의 `expires_at`까지 사용할 수 있습니다.

`GET /api/v2/jobs/{id}/events`의 SSE 스트림은 두 SDK에서 모두 `job.events()`로 노출되며, 그 위에 더해진 실시간 개선 기능입니다. 진행률 표시줄을 갱신하는 데 사용하세요. 이 스트림을 신뢰할 수 있는 소스로 사용하지 마세요. 이벤트 ID가 없고 재개 커서가 없으며, 연결이 해제된 동안 발생한 프레임은 사라집니다.

신뢰할 수 있는 경로가 스트림이나 웹훅이 아니라 폴링인 두 가지 이유:

* 워크플로는 오랜 시간 실행될 수 있습니다. 3초 정도 순간적으로 끊긴 연결 때문에 결과를 잃어서는 안 됩니다.
* 웹훅은 공개 주소가 있는 서비스에는 잘 동작합니다. 하지만 누군가의 데스크톱에서 포트를 수신 대기하지 않는 Blender 플러그인에는 동작하지 않으며, 그래서도 안 됩니다.

실질적인 효과는 모든 단계를 재개할 수 있다는 점입니다. 프로세스가 작업 중간에 중단되더라도 한 시간 뒤에 돌아와 `GET /api/v2/jobs/{id}`를 호출하면 상태와 출력이 여전히 있습니다. 다른 전송 방식도 적합한 경우에 나중에 추가될 수 있지만, 이 방식은 어디서나 동작하는 방식입니다.

## 기존 API와의 관계

지원 중단된 항목은 없습니다. `/prompt`, `/history`, `/ws`와 나머지도 계속 작동하고, [Cloud API](/ko/development/cloud/overview)도 계속 작동합니다. 현재 통합이 정상 작동한다면 이 중 어떤 것도 문제를 일으키지 않습니다. 두 API는 나란히 운영됩니다.

|              | Comfy API v2                         | 기존 API                            |
| ------------ | ------------------------------------ | --------------------------------- |
| **호환성**      | 버전 관리됨. v2 내에서는 추가 변경만 허용            | 릴리스 간 호환성 보장 없음                   |
| **동시성 모델**   | 여러 작업이 동시에 진행되며 각 작업에 영구 ID 부여       | 인스턴스 하나에서 한 번에 하나의 워크플로           |
| **실행 환경**    | Comfy Cloud 및 자체 호스팅 ComfyUI, 동일한 규약 | Cloud API와 ComfyUI Server API는 다름 |
| **공식 클라이언트** | Python 및 TypeScript SDK              | 없음                                |
| **적합한 용도**   | 새로운 통합                               | 이미 작동하는 통합                        |

## 첫 번째 버전의 범위

한 가지를 제대로: 워크플로를 실행하고 결과를 받아오는 것입니다. 입력을 업로드하고, API 형식 그래프를 제출하고, 실행 과정을 지켜보고, 출력을 내려받습니다.

의도적으로 이 범위가 전부입니다. 저장된 워크플로, 모델 라이브러리 관리, 노드 인트로스펙션, 명명된 워크플로 파라미터는 아직 여기에 없습니다. ComfyUI가 배포되는 모든 방식에서 진정으로 책임질 수 있는 작은 API 표면을 제공하는 쪽이, 그중 한 방식에서만 유지되는 큰 표면을 제공하는 것보다 낫습니다. 이 범위는 여기서부터 성장해 나갈 것입니다.

## 로컬 프록시

베타 기간 동안 자체 호스팅 ComfyUI는 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy)를 통해 v2를 사용합니다. 이 프록시는 인스턴스와 함께 실행되며 그 앞에서 v2 규격을 제공합니다. 오픈 소스이며 명시적으로 임시방편입니다. API가 안정화되면 이 기능은 ComfyUI 코어로 이동하고 프록시는 더 이상 필요하지 않게 됩니다.

## Python과 TypeScript를 먼저 지원하는 이유

ComfyUI를 대규모로 이미 운영 중인 분들에게 물었을 때 수요가 가장 많았던 곳입니다. 두 SDK는 동일하게 문서화된 HTTP 계약을 기반으로 하므로, 지금 바로 어떤 언어로든 API와 통신할 수 있습니다. 다른 언어의 공식 SDK를 원하신다면 [저희 Discord](https://discord.com/invite/comfyorg)의 `#developer-platform` 채널에서 알려 주세요.

## 여러분에게 바라는 점

API가 `0.1.x`인 데는 이유가 있으며, 앞으로 몇 주에 걸쳐 API 표면을 고정할 계획입니다. 메서드 이름, 클라이언트 형태, 이벤트 카탈로그, 오류 분류 체계, 실제 에셋 처리 방식은 지금은 모두 변경 비용이 낮습니다. [피드백](/ko/development/api-development/sdks#feedback)을 참고하세요.