Skip to main content
베타: Comfy API v2는 0.1.x 버전이며 API 표면은 여전히 변경될 수 있습니다. v2 내 변경 사항은 추가적으로 제공됩니다. 호환성을 깨뜨리는 변경은 v3로 출시됩니다.
외부 애플리케이션에서 ComfyUI 워크플로를 실행하기 위한 공식 버전 관리 HTTP API입니다: 입력 업로드, 워크플로 제출, 실행 관찰, 결과 검색. 대부분의 사용자는 이 API를 Python과 TypeScript로 래핑한 Comfy SDKs부터 시작해야 합니다. 다른 언어로 작업하는 경우 이러한 엔드포인트를 직접 호출하세요. 전체 엔드포인트 문서는 OpenAPI 사양에서 생성된 이 섹션의 API Reference 페이지에 있습니다.

​
v2 실행 환경

동일한 API를 세 가지 환경에서 제공하므로, 기본 URL만 변경하면 하나의 통합을 이들 사이에서 옮길 수 있습니다. Comfy Cloud. https://cloud.comfy.org의 관리형 멀티 테넌트 서비스입니다. API 키를 만들면 어떤 워크플로든 제출할 수 있습니다. 크레딧, 모델 탐색, 대기열 관리 같은 Cloud 전용 기능은 v2가 아니라 v1 Cloud API에 있습니다. Comfy API 배포. Developer Platform을 통해 배포한 환경은 https://{deployment}.run.comfy.app에 자체 전용 엔드포인트를 가지며, 동일한 API 키로 같은 v2 API를 제공합니다. Comfy API 배포는 하나의 고정된 환경에서 워크플로를 실행하므로 독립적으로 확장되며, GET /workflow는 실행된 그래프를 반환합니다. 빌드와 배포 방법은 Comfy API 배포 가이드를 참조하세요. 오픈소스 ComfyUI, 프록시 경유. 베타 기간 동안 자체 호스팅 ComfyUI는 함께 실행되는 작은 오픈소스 서비스인 comfy-api-proxy를 통해 v2를 지원합니다:
기본적으로 127.0.0.1:8188의 ComfyUI를 프록시하고 127.0.0.1:8189에서 v2 API를 제공하며, 루프백에만 바인딩합니다. 인증은 기본적으로 꺼져 있고 선택적으로 정적 Bearer 토큰을 사용할 수 있습니다. 이 프록시는 임시 방편입니다. v2가 안정화되면 ComfyUI 코어로 이동하므로 프록시는 더 이상 필요하지 않습니다. 구성 세부 정보는 SDK 가이드의 자체 ComfyUI 실행을 참조하세요.

​
설계 원칙

  • 폴링 우선. 모든 기능은 일반 GET 폴링으로 접근할 수 있습니다. SSE 스트림은 실시간 개선 사항일 뿐, 결코 진실의 원천은 아닙니다.
  • 모든 것은 재개 가능합니다. 제출은 멱등적이며, 작업 상태와 출력은 expires_at까지 ID로 검색할 수 있습니다. 출력에 대해 반환되는 URL의 수명은 그보다 짧습니다. 출력 URL과 유효 기간을 참조하세요.
  • 콘텐츠 주소 지정 에셋. 에셋은 서버에서 계산된 blake3 해시를 키로 하는 blob에 대한 UUID 식별 레코드입니다. 따라서 동일한 입력이 두 번 업로드되지 않습니다.
  • 링크를 따르고 URL을 직접 만들지 마세요. 응답에는 후속 URL이 포함되어 있습니다.
이러한 설계 원칙에 대한 근거는 디자인 노트를 참조하세요.

​
기본 URL

​
엔드포인트 카테고리

​
출력 URL과 유지 기간

“내 출력의 URL”에는 서로 다른 세 가지 수명이 적용되며, 이들은 같은 숫자가 아닙니다. 자체 사용자에게 출력을 보여주는 모든 애플리케이션은 이 세 가지를 모두 고려해야 합니다.

​
두 가지 URL 형태

실질적인 결과는 다음과 같습니다. Output.url은 공유 가능한 링크가 아닙니다. 사용자의 브라우저가 로드하는 <img src>에 넣으면, 그 브라우저가 여러분의 API 키를 가지고 있지 않기 때문에 401이 발생합니다. 배포할 수 있는 것은 서명된 URL입니다. 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를 참조하세요. 먼저 Router 제한 사항을 검토하세요. Router는 아직 일반 공개되지 않았습니다.