왜 새로운 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도 계속 작동합니다. 현재 통합이 정상 작동한다면 이 중 어떤 것도 문제를 일으키지 않습니다. 두 API는 나란히 운영됩니다.
첫 번째 버전의 범위
한 가지를 제대로: 워크플로를 실행하고 결과를 받아오는 것입니다. 입력을 업로드하고, API 형식 그래프를 제출하고, 실행 과정을 지켜보고, 출력을 내려받습니다. 의도적으로 이 범위가 전부입니다. 저장된 워크플로, 모델 라이브러리 관리, 노드 인트로스펙션, 명명된 워크플로 파라미터는 아직 여기에 없습니다. ComfyUI가 배포되는 모든 방식에서 진정으로 책임질 수 있는 작은 API 표면을 제공하는 쪽이, 그중 한 방식에서만 유지되는 큰 표면을 제공하는 것보다 낫습니다. 이 범위는 여기서부터 성장해 나갈 것입니다.로컬 프록시
베타 기간 동안 자체 호스팅 ComfyUI는 comfy-api-proxy를 통해 v2를 사용합니다. 이 프록시는 인스턴스와 함께 실행되며 그 앞에서 v2 규격을 제공합니다. 오픈 소스이며 명시적으로 임시방편입니다. API가 안정화되면 이 기능은 ComfyUI 코어로 이동하고 프록시는 더 이상 필요하지 않게 됩니다.Python과 TypeScript를 먼저 지원하는 이유
ComfyUI를 대규모로 이미 운영 중인 분들에게 물었을 때 수요가 가장 많았던 곳입니다. 두 SDK는 동일하게 문서화된 HTTP 계약을 기반으로 하므로, 지금 바로 어떤 언어로든 API와 통신할 수 있습니다. 다른 언어의 공식 SDK를 원하신다면 저희 Discord의#developer-platform 채널에서 알려 주세요.
여러분에게 바라는 점
API가0.1.x인 데는 이유가 있으며, 앞으로 몇 주에 걸쳐 API 표면을 고정할 계획입니다. 메서드 이름, 클라이언트 형태, 이벤트 카탈로그, 오류 분류 체계, 실제 에셋 처리 방식은 지금은 모두 변경 비용이 낮습니다. 피드백을 참고하세요.