- Blender나 Krita와 같은 다른 애플리케이션 내부에서 콘텐츠를 생성하는 플러그인
- 사용자를 대신하여 생성 작업을 실행하는 소비자 앱
- 배치 파이프라인, 예를 들어 비디오의 모든 프레임에 워크플로 하나를 실행하는 경우
- 한 번에 많은 워크플로를 동시에 실행해야 하는 백엔드 서비스
이 SDK는 ComfyUI를 외부에서 구동합니다. ComfyUI 내부에서 실행되는 커스텀 노드나 프런트엔드 확장 프로그램을 작성하는 경우에는 커스텀 노드 개발을 대신 참조하세요. 이들은 별도의 API 집합입니다.
설치
빠른 시작
입력 이미지를 업로드하고 워크플로를 실행한 다음 결과를 디스크에 기록합니다.workflow_api.json은 API 형식으로 저장된 워크플로입니다. "10"과 "9"는 해당 파일의 노드 ID로, 입력 이미지를 받는 노드와 결과를 가져올 출력 노드를 나타냅니다.
에셋 핸들은 지연 방식으로 동작합니다. photo.png는 로컬에서 해시되며 서버에 해당 바이트가 없을 때만 업로드되므로, 동일한 입력으로 다시 실행해도 비용이 들지 않습니다.
run()은 작업을 제출하고 터미널 상태에 도달할 때까지 대기합니다. 실행되는 동안 다른 작업을 수행하려면 submit()을 대신 사용하고 이벤트 스트림을 확인하세요.
대신 자체 ComfyUI를 대상으로 실행하려면 한 줄을 변경하고 키를 제거하면 됩니다. Comfy("http://127.0.0.1:8189"). 아래를 참조하세요.
기본 URL 선택
Comfy Cloud
즉시 사용할 수 있습니다. API 키를 생성하여 클라이언트에 전달하세요.API 액세스에는 유료 Comfy Cloud 구독이 필요합니다. 무료 티어에는 포함되지 않습니다. 동시에 실행할 수 있는 작업 수는 티어에 따라 다릅니다. Cloud API 개요를 참조하세요.
자체 ComfyUI
베타 기간 동안 v2 API는 ComfyUI와 함께 실행되는 작은 오픈소스 서비스인 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()는 작업 상태의 라이브 스트림을 제공합니다. 노드와 단계 진행 상황, 미리보기 프레임, 그리고 각 출력이 커밋되는 순간을 보여줍니다. 연결이 끊어지면 자동으로 다시 연결됩니다.
Preview.to_pil()에는 선택적 Pillow extra가 필요합니다: pip install "comfy-sdk[pil]".
result()는 완료된 작업을 반환하거나, 실행이 실패한 경우 노드 수준의 세부 정보와 함께 JobFailed를 발생시킵니다. 전체 이벤트 카탈로그는 해당 언어의 SDK README를 참조하세요.
스트림은 재생 가능한 로그가 아니라 실시간 피드입니다. 결과를 위해 의존할 수 있도록 존재하는 것이 아니라, 진행 상황을 표시하기 위해 존재합니다. 작업을 폴링하는 것이 가장 신뢰할 수 있는 정보이며, run(), wait(), result()는 자동으로 폴링을 사용합니다. 그 이유는 설계 노트를 참조하세요.
현재 SDK가 다루는 범위
첫 번째 버전은 한 가지 작업을 제대로 수행합니다. 워크플로를 실행하고 결과를 돌려받는 것입니다.- 에셋. 파일, 바이트, 스트림 또는 URL에서 입력 핸들을 생성합니다. 핸들은 지연(lazy) 방식이며 콘텐츠 주소 기반이므로 동일한 입력으로 다시 실행해도 다시 업로드되지 않습니다.
- 제출. API 형식의 그래프를 제출합니다. 제출은 멱등적이며, 실행 대기열이 가득 찬 경우 제한된 예산 내에서 자동으로 재시도됩니다.
- 실행.
wait()으로 폴링하거나events()를 통해 실시간 진행 상황을 추적합니다. - 출력. 디스크에 쓰거나, 메모리에 버퍼링하거나, 바이트 범위를 가져오거나, 단기 다운로드 URL을 받을 수 있습니다.
- 오류. 원시 상태 코드 대신
JobFailed,Unauthorized,InsufficientCredits,QueueFull과 같은 타입화된 예외를 제공합니다. - 취소. 실행 중인 작업을 취소할 수 있습니다. TypeScript는 추가로 모든 호출에서
AbortSignal을 허용합니다.
Comfy 클라이언트와 AsyncComfy 클라이언트를 모두 제공합니다. TypeScript는 비동기 전용입니다.
이 버전에는 포함되지 않는 것: 저장된 워크플로 관리, 모델 라이브러리, 노드 인트로스펙션, 명명된 워크플로 파라미터. 설계 노트에서 API 표면이 이렇게 작게 시작하는 이유를 설명합니다.
참조
SDK README는 각 언어에 대한 전체 참조 자료로, 인증, 에셋, 오류 및 저수준 이스케이프 해치를 포함합니다.Python SDK
comfy-sdk on PyPI. 동기 및 비동기 클라이언트를 제공합니다.TypeScript SDK
@comfyorg/sdk on npm. 타입 기반 비동기 클라이언트와 저수준 클라이언트를 갖추고 있습니다.Comfy API v2 참조
두 SDK의 기반이 되는 HTTP API입니다. 어떤 언어에서든 직접 사용할 수 있습니다.
설계 노트
이 API가 존재하는 이유, 기존 ComfyUI API와의 관계, 그리고 향후 계획을 설명합니다.
피드백
0.1.x는 의도적인 버전입니다. 메서드 이름, 클라이언트 형태, 이벤트 카탈로그, 오류 분류 체계, 그리고 실제로 에셋 처리가 어떻게 느껴지는지는 모두 아직 변경 비용이 낮으며, 앞으로 몇 주 안에 API 표면을 확정할 계획입니다. 그 이후에는 “장기 지원”이라는 말이 더 이상 여러분을 위해 수정해 드릴 수 없다는 의미가 됩니다.
그러니 무엇이 어색한지, 무엇을 기대했는데 찾지 못했는지, 그리고 결국 어떻게 우회해서 해결했는지 알려주세요. 그런 피드백을 보내실 곳은 저희 Discord의 #developer-platform 채널입니다.
다른 언어로 된 퍼스트파티 SDK를 원하신다면 그곳에서 말씀해 주세요. 두 SDK 모두 동일한 문서화된 HTTP 계약을 기반으로 하므로 어떤 언어든 오늘날 API와 통신할 수 있지만, 저희는 수요가 어디에 있는지 알고 싶습니다.