> ## Documentation Index
> Fetch the complete documentation index at: https://comfyuiwiki.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Comfy API v2 개요
> 공식 Comfy API v2 레퍼런스: 입력을 업로드하고 작업을 제출하며 결과를 폴링하여 외부 애플리케이션에서 ComfyUI 워크플로우를 실행합니다.
**베타:** Comfy API v2는 `0.1.x` 버전이며 API 표면은 여전히 변경될 수 있습니다. v2 내 변경 사항은 추가적으로 제공됩니다. 호환성을 깨뜨리는 변경은 v3로 출시됩니다.
외부 애플리케이션에서 ComfyUI 워크플로를 실행하기 위한 공식 버전 관리 HTTP API입니다: 입력 업로드, 워크플로 제출, 실행 관찰, 결과 검색.
대부분의 사용자는 이 API를 Python과 TypeScript로 래핑한 [Comfy SDKs](/ko/development/api-development/sdks)부터 시작해야 합니다. 다른 언어로 작업하는 경우 이러한 엔드포인트를 직접 호출하세요. 전체 엔드포인트 문서는 OpenAPI 사양에서 생성된 이 섹션의 API Reference 페이지에 있습니다.
## v2 실행 환경
동일한 API를 세 가지 환경에서 제공하므로, 기본 URL만 변경하면 하나의 통합을 이들 사이에서 옮길 수 있습니다.
**Comfy Cloud.** `https://cloud.comfy.org`의 관리형 멀티 테넌트 서비스입니다. [API 키](/ko/development/api-development/getting-an-api-key)를 만들면 어떤 워크플로든 제출할 수 있습니다. 크레딧, 모델 탐색, 대기열 관리 같은 Cloud 전용 기능은 v2가 아니라 [v1 Cloud API](/ko/development/cloud/overview)에 있습니다.
**Comfy API 배포.** [Developer Platform](https://platform.comfy.org)을 통해 배포한 환경은 `https://{deployment}.run.comfy.app`에 자체 전용 엔드포인트를 가지며, 동일한 API 키로 같은 v2 API를 제공합니다. Comfy API 배포는 하나의 고정된 환경에서 워크플로를 실행하므로 독립적으로 확장되며, `GET /workflow`는 실행된 그래프를 반환합니다. 빌드와 배포 방법은 [Comfy API 배포 가이드](/ko/development/serverless/overview)를 참조하세요.
**오픈소스 ComfyUI, 프록시 경유.** 베타 기간 동안 자체 호스팅 ComfyUI는 함께 실행되는 작은 오픈소스 서비스인 [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy)를 통해 v2를 지원합니다:
```bash theme={null}
pip install comfy-api-proxy
comfy-api-proxy
```
기본적으로 `127.0.0.1:8188`의 ComfyUI를 프록시하고 `127.0.0.1:8189`에서 v2 API를 제공하며, 루프백에만 바인딩합니다. 인증은 기본적으로 꺼져 있고 선택적으로 정적 Bearer 토큰을 사용할 수 있습니다. 이 프록시는 임시 방편입니다. v2가 안정화되면 ComfyUI 코어로 이동하므로 프록시는 더 이상 필요하지 않습니다. 구성 세부 정보는 SDK 가이드의 [자체 ComfyUI 실행](/ko/development/api-development/sdks#자체-comfyui)을 참조하세요.
## 설계 원칙
* **폴링 우선.** 모든 기능은 일반 GET 폴링으로 접근할 수 있습니다. SSE 스트림은 실시간 개선 사항일 뿐, 결코 진실의 원천은 아닙니다.
* **모든 것은 재개 가능합니다.** 제출은 멱등적이며, 작업 상태와 출력은 `expires_at`까지 ID로 검색할 수 있습니다. 출력에 대해 반환되는 URL의 수명은 그보다 짧습니다. [출력 URL과 유효 기간](#출력-url과-유지-기간)을 참조하세요.
* **콘텐츠 주소 지정 에셋.** 에셋은 서버에서 계산된 blake3 해시를 키로 하는 blob에 대한 UUID 식별 레코드입니다. 따라서 동일한 입력이 두 번 업로드되지 않습니다.
* **링크를 따르고 URL을 직접 만들지 마세요.** 응답에는 후속 URL이 포함되어 있습니다.
이러한 설계 원칙에 대한 근거는 [디자인 노트](/ko/development/api-development/sdks-design)를 참조하세요.
## 기본 URL
| 환경 | URL | 인증 |
| -------------------------------------------------------------------------- | ------------------------------------ | --------------------------------- |
| Comfy Cloud | `https://cloud.comfy.org` | `Authorization: Bearer ` |
| Comfy API 배포 | `https://{deployment}.run.comfy.app` | `Authorization: Bearer ` |
| 자체 호스팅, [comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy) 경유 | `http://127.0.0.1:8189` | 기본적으로 없음, 선택적 정적 Bearer 토큰 |
## 엔드포인트 카테고리
| 카테고리 | 설명 |
| ---- | -------------------------------------------------------------- |
| 에셋 | 콘텐츠 주소 지정 blob을 기반으로 하는 UUID 식별 레코드입니다. 입력을 업로드하고 출력을 다운로드합니다. |
| 작업 | 워크플로의 단일 실행입니다. 영속적이며, 폴링 가능하고, 취소 가능합니다. |
## 출력 URL과 유지 기간
"내 출력의 URL"에는 서로 다른 세 가지 수명이 적용되며, 이들은 같은 숫자가 아닙니다. 자체 사용자에게 출력을 보여주는 모든 애플리케이션은 이 세 가지를 모두 고려해야 합니다.
### 두 가지 URL 형태
| 형태 | 어디서 얻는가 | 제3자가 열 수 있는가? | 유지 기간 |
| ---------------------------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------- | --------------------------------- |
| 콘텐츠 엔드포인트, `{base}/api/v2/assets/{id}/content` | 작업의 `outputs` 각 항목에 있는 `url` | 아니요. 인증이 필요한 라우트이며 API 키 없이는 `401`을 반환합니다. | 안정적입니다. 에셋이 존재하는 동안 계속 해석됩니다. |
| 서명된 스토리지 URL | `Asset` 응답의 `url`, 콘텐츠 엔드포인트가 리디렉션하는 `302` `Location`, 그리고 두 SDK의 `getDownloadUrl()` | 예. 자체 인증 정보를 포함하므로 브라우저나 다른 서비스가 자체 키 없이 읽을 수 있습니다. | 짧습니다. 현재 Comfy Cloud에서 대략 6시간입니다. |
실질적인 결과는 다음과 같습니다. `Output.url`은 공유 가능한 링크가 아닙니다. 사용자의 브라우저가 로드하는 `![]()
`에 넣으면, 그 브라우저가 여러분의 API 키를 가지고 있지 않기 때문에 `401`이 발생합니다. 배포할 수 있는 것은 서명된 URL입니다.
[comfy-api-proxy](https://github.com/Comfy-Org/comfy-api-proxy) 뒤에 있는 자체 호스팅 ComfyUI에는 서명된 URL이 전혀 없습니다. 프록시가 콘텐츠 엔드포인트에서 바이트를 제공하고 노멀(normal) 인증이 적용되며, SDK는 만료를 `null`(Python: `None`)로 보고합니다.
### 서명된 URL의 만료 읽기
Comfy Cloud 및 Comfy API 배포에서 서명된 URL은 **약 6시간**의 유효 기간으로 발급됩니다. 이 숫자는 API 계약의 일부가 아니라 서버 측 설정이므로, 대략적인 크기 정도로 취급하고 절대 하드코딩하지 마세요. 주어진 응답에서 만료를 읽으세요.
* `Asset` 응답의 `url_expires_at`은 같은 응답에 있는 `url`의 실제 만료 시각입니다.
* `getDownloadUrl()`은 URL과 함께 이를 반환하며, TypeScript에서는 `expiresAt`, Python에서는 `expires_at`입니다.
### 작업 출력의 `url_expires_at`은 다른 숫자입니다
작업의 `outputs` 항목에 있는 `url_expires_at`은 서명된 URL의 만료 시각이 **아닙니다**. Comfy Cloud에서는 작업 자체의 `expires_at`을 반복하는데, 이는 현재 작업의 `created_at`에 고정 30일 창을 더한 값입니다.
그 창은 자리 표시자입니다. 플랫폼에는 아직 이를 뒷받침하는 작업 보존 정책이나 가비지 컬렉션 정책이 없으므로, 30일은 해당 필드가 null이 아니도록 해주는 임시값일 뿐, 출력이 얼마나 오래 조회 가능한지에 대한 약정이 아닙니다. 이를 약속으로 읽지 말고, 이를 기준으로 캐시를 구성하지 마세요. 실제 보존 정책이 이를 대체하면 이 페이지가 업데이트될 예정입니다.
### 자체 제품에서 출력 표시하기
하루가 지난 뒤에도 출력을 계속 표시하려면 다음 중 하나를 하세요.
* **바이트를 다시 호스팅하세요.** 출력을 한 번 다운로드하여 자체 스토리지로 복사하세요. 대부분의 애플리케이션이 여기에 이르게 됩니다.
* **필요할 때 다시 발급하세요.** 에셋 `id`를 영구 저장한 다음, 렌더링하는 시점에 이를 새 URL(`GET /api/v2/assets/{id}` 또는 `getDownloadUrl()`)로 해석하고 그 URL을 즉시 사용하세요.
* **프록시하세요.** 이미 API 키를 보유한 자체 백엔드에서 `Output.url`을 가져와 사용자에게 바이트를 스트리밍하세요.
통하지 않는 방법은 서명된 URL을 영구 저장하는 것입니다. 이는 며칠이 아니라 몇 시간 동안만 유효하므로, 저장된 복사본은 로컬 테스트 동안에는 계속 작동하다가 만료되면 사용자에게서 깨집니다.
## Comfy Router
Comfy API v2는 제출 후 폴링하는 영속적인 작업(job)으로 워크플로를 실행합니다. 모델을 직접 호출해야 하는 경우(파트너 모델 하나, 요청 하나, 모델 고유의 네이티브 입력 및 출력)에는 [Comfy Router](/ko/development/comfy-router/quickstart)를 참조하세요. 먼저 [Router 제한 사항](/ko/development/comfy-router/limitations)을 검토하세요. Router는 아직 일반 공개되지 않았습니다.