Files

T

2026-05-19 18:08:09 +09:00

9.0 KiB

Raw Blame History

id, title, category, status, verification_status, canonical_id, aliases, duplicate_of, source_trust_level, confidence_score, created_at, updated_at, review_reason, merge_history, tags, raw_sources, applied_in, github_commit

title

ComfyUI API

🎯 한 줄 통찰 (One-line insight)

ComfyUI API는 노드 기반의 비주얼 워크플로를 **실행 가능한 데이터 구조(JSON)**로 직렬화하여, 창의적 프로세스를 자동화된 프로덕션 파이프라인으로 전환하는 핵심 인터페이스이다 [1, 2].

🧠 핵심 개념 (Core concepts)

API Format (workflow_api.json): 사용자 인터페이스(UI) 메타데이터(노드 위치, 크기, 그룹 등)를 제거하고 오직 백엔드 엔진의 실행에 필요한 노드 유형과 입력 연결 정보만을 포함하는 간소화된 그래프 포맷이다 [3-5].
Dev Mode Options: API 포맷으로 워크플로를 내보내기 위해 반드시 활성화해야 하는 설정으로, 활성화 시 'Save (API format)' 버튼이 노출된다 [6-8].
Serialization & Mapping: 노드망을 JSON 형식의 딕셔너리로 변환하며, 각 노드는 고유한 numeric ID(예: "37")를 키로 사용하여 class_type과 inputs 값을 정의한다 [9-11].
Prompt Endpoint (/prompt): 생성된 API JSON 페이로드를 ComfyUI 서버의 /prompt 엔드포인트로 POST 요청을 보내 실제 실행을 트리거한다 [10, 12].

🧩 추출된 패턴 (Extracted patterns)

Execution Model Inversion: 엔진이 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 식별하고 실행한다 [13].
Bifurcation of Formats: 시각적 편집을 위한 Frontend 포맷(workflow.json)과 프로그래밍적 실행을 위한 Backend 포맷(workflow_api.json)을 분리하여 운영 효율성을 극대화한다 [3, 14].
Metadata Recovery: PNG 파일의 tEXt 또는 zTXt 청크에 숨겨진 워크플로 JSON 데이터를 exiftool이나 전용 추출기를 통해 복구하여 공유 및 재사용하는 패턴이 발견된다 [15-17].

📖 세부 내용 (Details)

1. API JSON 생성 및 구조적 특징

API 포맷 JSON은 백엔드 실행 최적화를 위해 설계되었다.

데이터 구조: 루트 키는 노드 ID(문자열)이며, 각 값은 class_type과 inputs 딕셔너리를 포함한다 [10, 18].
연결 표현: 노드 간의 링크는 별도의 배열이 아닌 노드 입력 내에서 [origin_node_id, output_slot_index] 형태의 참조로 직접 임베딩된다 [3, 19].
위젯 값 전환: GUI에서 사용자가 입력한 위젯 값(시드, 텍스트 등)은 API JSON의 inputs 필드로 직접 매핑되어 고정된 값이 된다 [19].

2. 프로그래밍적 조작 및 자동화

개발자는 템플릿화된 API JSON을 Python 등을 통해 동적으로 수정하여 대량 생성을 자동화할 수 있다.

입력값 교체: json 라이브러리를 사용하여 특정 노드 ID의 inputs 필드(예: 프롬프트 텍스트, 시드 값)를 런타임에 변경한다 [10, 20].
이미지 주입: 외부 이미지를 API로 전달할 때는 Load Image (Base64) 노드를 사용하거나 이미지를 서버의 input 디렉토리에 업로드한 후 파일명으로 참조한다 [21, 22].
결과 수신: 생성 진행 상황과 결과 이미지는 WebSocket 통신을 통해 실시간으로 모니터링하며, SaveImageWebsocket 노드를 사용하여 바이너리 데이터를 직접 수신할 수 있다 [22].

3. 고도화된 생성 도구

ComfyUI-to-Python-Extension: JSON 워크플로를 독립적으로 실행 가능한 .py 스크립트로 변환하여 서버 없이도 헤드리스 환경에서 실행 가능하게 한다 [23, 24].
Comfy API Simplified: 노드 ID 대신 사용자가 지정한 노드 제목(title)으로 파라미터를 설정할 수 있게 하여 워크플로 수정 시 코드의 파손을 방지한다 [23, 25].
LLM 기반 생성: 자연어 설명을 입력하면 Qwen2.5와 같은 모델이 이를 해석하여 유효한 노드 그래프 구조를 자동으로 생성하고 빌드한다 [26, 27].

⚖️ 모순 및 업데이트 (Contradictions & updates)

하위 호환성 문제: ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [28].
포맷의 비가역성: API 포맷 JSON은 실행 효율은 높으나, 이를 다시 GUI로 드래그하여 로드할 경우 시각적 레이아웃(노드 위치 등)이 유실된 '스켈레톤' 상태로 나타나 편집이 어렵다 [12, 29].

🛠️ 적용 사례 (Applied in summary)

comfyui-workflow-to-api-converter-endpoint: 클라이언트 사이드의 JS 로직을 Python으로 변환하여 서버 측에서 일반 JSON을 API JSON으로 즉시 변환하는 엔드포인트를 구현함 (커밋: bc85382) [12, 30].
ComfyUI-WorkflowGenerator: 자연어 프롬프트를 기반으로 3단계 파이프라인(생성-검증-빌드)을 거쳐 실행 가능한 워크플로를 생성하는 시스템 (커밋: 82df278) [27, 31].
ComfyUI-to-Python-Extension: 워크플로를 Python 코드로 번역하여 자동화 및 반복 생성에 최적화된 스크립트를 제공함 (커밋: 6cdcc23) [24, 32].

✅ 검증 상태 및 신뢰도

상태: draft
검증 단계: conceptual (다수의 GitHub 프로젝트를 통해 실용성 입증됨)
출처 신뢰도: B (공식 문서 및 오픈소스 프로젝트 README 기반)
중복 검사 결과: 신규 생성

상위/유사 개념

[아키텍처/기반 기술]

Workflow JSON
- 연결 이유: API 데이터의 근간이 되는 스키마 규격
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 속성 및 링크 스키마 v1.0의 기술적 제약 사항 [33].

[구현/활용 도구]

API Format
- 연결 이유: ComfyUI 서버 통신을 위한 필수 데이터 포맷
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 메타데이터 제거 및 실행 최적화 로직 [5].
ComfyUI-Manager
- 연결 이유: API 실행 시 누락된 커스텀 노드 의존성 해결 도구
- 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 class_type을 기반으로 한 자동 노드 설치 프로세스 [34].

심층 후속 질문 (Deeper Research Questions)

API JSON의 inputs 필드에서 노드 참조 시 사용되는 슬롯 인덱스의 정확한 매핑 규칙은 무엇인가? [35]
Execution Model Inversion이 대규모 워크플로에서 실제 성능(VRAM/연산)에 미치는 정량적 영향은 어느 정도인가? [13]
LLM 기반 워크플로 생성 시 NodeValidator가 사용하는 시맨틱 임베딩 방식은 커스텀 노드의 정확도를 어떻게 보장하는가? [36, 37]
PNG 메타데이터가 손상된 경우, exiftool 외에 바이너리 수준에서 워크플로를 복구할 수 있는 대안적 방법이 있는가? [17, 38]
comfyui-workflow-to-api-converter가 처리하는 1MB 요청 제한의 기술적 근거와 대규모 워크플로(Flux 등) 대응 방안은 무엇인가? [39, 40]

실무 적용 맥락 (Practical Application Contexts)

Implementation: /prompt 엔드포인트에 전송할 JSON 페이로드를 생성하기 위해 GUI의 'Dev mode'를 활용하여 템플릿을 확보한다 [8].
System Design: 프로덕션 환경에서는 사용자의 입력을 수신하는 미들웨어를 구축하고, 템플릿 JSON의 특정 노드 ID 값을 동적으로 치환하여 ComfyUI 인스턴스에 전달한다 [22, 41].
Operation / Maintenance: 워크플로 변경 시 노드 ID가 변할 수 있으므로, 유지보수성을 위해 comfy_api_simplified와 같이 노드 제목 기반으로 접근하는 래퍼 사용을 권장한다 [23, 25].
Learning Path: 기본 UI 사용법 숙지 → Dev mode 활성화 및 API JSON 구조 분석 → Python requests 및 websocket을 이용한 원격 제어 순으로 학습한다 [42, 43].

인접 주변 주제 (Adjacent Topics)

Comfy GPT
- 확장 방향: AI 에이전트가 직접 노드를 조립하고 디버깅하는 자가 최적화 시스템 연구 [27, 44].
Model Hashing
- 확장 방향: 파일명 대신 해시값을 사용하여 API 호출 시 모델 불일치 문제를 해결하는 기술 [45].

📝 변경 이력 (Change history)

2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources)

9.0 KiB Raw Blame History