- 10_Wiki/Comfyui/: ComfyUI docs generated via /wikify
- 00_Raw/_youtube/: /youtube extraction outputs
- Move some 00_Raw originals into 10_Wiki/Topics_meeting; remove empty canvases and stray files
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
ComfyUI API Integration은 시각적 노드 그래프를 실행 최적화된 **API JSON(Backend Format)**으로 직렬화하여, 외부 애플리케이션 및 서버리스 환경에서 생성 AI 워크플로우를 프로그래밍 방식으로 자동화하고 확장하는 핵심 매개체이다 [1-3].
🧠 핵심 개념 (Core concepts)
워크플로우 포맷의 이분화 (Bifurcation): 사용자의 시각적 편집을 위한 'Frontend Format(workflow.json)'과 서버 실행을 위해 UI 메타데이터를 제거한 'API Format(workflow_api.json)'으로 구분된다 [2, 4-6].
API JSON 직렬화: 노드 위치, 크기, 그룹 등 시각적 정보를 배제하고 노드 클래스(class_type), 입력 매개변수(inputs), 노드 간 연결 관계만을 포함하는 압축된 실행 그래프이다 [2, 6, 7].
개발자 모드 (Dev Mode): 표준 UI에서는 숨겨져 있으며, 설정에서 활성화해야만 API 전용 JSON을 내보낼 수 있는 기능이 활성화된다 [8-12].
엔드포인트 연동: 생성된 API JSON은 ComfyUI 서버의 /prompt 엔드포인트로 전송되어 실제 이미지나 미디어 생성 명령으로 변환된다 [2, 4, 12, 13].
🧩 추출된 패턴 (Extracted patterns)
개발자 모드 활성화 패턴:Settings 아이콘 클릭 → Enable Dev mode Options 체크 → 메뉴의 Save (API Format) 버튼 사용 [8-11, 14].
메타데이터 추출 패턴: PNG/WebP 이미지의 tEXt 또는 zTXt 청크에 포함된 JSON 데이터를 exiftool이나 전용 추출 도구를 통해 복구하여 재사용하는 방식 [15-18].
동적 템플릿 패턴: 기본 JSON 파일을 로드한 후 Python 딕셔너리 조작을 통해 특정 노드 ID의 seed, prompt, image 등의 값을 실시간으로 변경하여 큐에 삽입하는 전략 [13, 19, 20].
고유 식별자(ID) 타겟팅: 각 노드에 부여된 숫자형 문자열 키(예: "37")를 사용하여 특정 노드의 입력 필드에 접근하는 패턴 [5, 20].
📖 세부 내용 (Details)
ComfyUI 워크플로우 JSON은 생성 AI 프로세스를 **유향 비순환 그래프(DAG)**로 정의하며, 이를 직렬화함으로써 이식성과 자동화를 실현한다 [1].
1. 워크플로우 JSON의 주요 유형 및 구조
Frontend JSON (workflow.json): Litegraph 표준을 따르며 노드 좌표, 그룹화, 색상 등 캔버스 레이아웃 정보를 포함한다 [2, 5, 21].
API JSON (workflow_api.json): 백엔드 엔진이 프롬프트를 실행하는 데 필요한 논리적 연결만 남긴 효율적인 그래프이다 [2, 4, 6]. 링크는 별도 객체가 아닌 노드 입력 내에 직접 임베딩된다 [2, 22].
구조적 제약: JSON v1.0 스키마에 따라 각 노드는 고유 id, type, inputs, outputs를 가져야 하며, 실행 엔진은 출력 노드에서 역방향으로 그래프를 탐색하여 필요한 의존성만 실행하는 '실행 모델 반전' 방식을 사용한다 [23-25].
2. JSON 생성 및 획득 방법
수동 내보내기: 웹 인터페이스에서 개발자 모드를 활성화한 후 전용 저장 버튼을 사용한다 [8, 9, 11].
알고리즘 추출: ComfyUI가 생성한 PNG 파일에는 워크플로우가 메타데이터로 자동 저장되므로, 이를 드래그 앤 드롭하거나 exiftool 명령어를 사용하여 추출할 수 있다 [15, 17, 26-28].
자연어 기반 생성: LLM(예: Qwen2.5-14B)을 사용하여 자연어 설명을 논리적 그래프 구조로 합성하고 로컬 노드 카탈로그와 대조하여 유효한 JSON으로 변환하는 방식이 도입되었다 [29-32].
3. 프로그래밍 방식의 통합 및 변환
Python 직접 조작: Python의 json 라이브러리를 사용하여 노드 ID를 기반으로 텍스트나 이미지 데이터를 업데이트한다 [19, 20]. 이미지는 주로 Base64로 인코딩되어 JSON 내에 직접 포함된다 [13, 33].
추상화 래퍼:comfy_api_simplified와 같은 라이브러리는 숫자 ID 대신 노드 제목으로 매개변수를 설정하게 하여 유지보수성을 높인다 [34, 35].
스크립트 변환:ComfyUI-to-Python-Extension은 JSON 워크플로우를 실행 가능한 독립형 .py 스크립트로 변환하여 헤드리스 환경에서 실행할 수 있게 한다 [34, 36, 37].
4. API 기반 자동화 및 배포
서버리스 플랫폼: Replicate나 Mystic 같은 서비스는 API JSON 블롭을 입력받아 클라우드 GPU에서 실행하고 결과를 반환하는 엔드포인트를 제공한다 [9, 38-40].
의존성 관리: JSON 로드 시 누락된 커스텀 노드는 '빨간 박스'로 표시되며, ComfyUI-Manager를 통해 자동으로 식별 및 설치할 수 있다 [41-43].
⚖️ 모순 및 업데이트 (Contradictions & updates)
포맷 호환성 문제: 표준 저장 방식으로 생성된 JSON은 API 엔드포인트에서 오류를 발생시키므로 반드시 API 포맷으로의 변환이 필요하다 [12].
메타데이터 손실: 소셜 미디어나 이미지 편집기(GIMP 등)를 통해 이미지를 전송 또는 수정할 경우 워크플로우 메타데이터가 삭제될 수 있다는 경고가 반복적으로 확인된다 [16, 26, 44, 45].
노드 ID 변동성: 워크플로우를 UI에서 수정하면 노드 ID가 변경될 수 있어, 하드코딩된 Python 스크립트가 파손될 위험이 존재한다 [19, 34]. 이에 대한 해결책으로 노드 제목 기반 매핑이 권장된다 [34, 35].
🛠️ 적용 사례 (Applied in summary)
서버 측 변환 엔드포인트:comfyui-workflow-to-api-converter-endpoint는 클라이언트 측의 자바스크립트 로직을 파이썬으로 변환하여 서버에서 일반 JSON을 API JSON으로 실시간 변환하는 /workflow/convert 엔드포인트를 구현했다 [12, 46, 47].
독립 실행형 스크립트 변환:pydn/ComfyUI-to-Python-Extension 프로젝트는 Save As Script 기능을 통해 워크플로우를 .py 파일로 다운로드하여 자동화된 실행 환경을 구축했다 [37, 48].
매개변수 스케줄링:comfy_api_simplified 라이브러리는 수백 개의 이미지를 야간에 생성하기 위해 여러 프롬프트와 매개변수를 반복 실행하는 예제 코드를 제공한다 [35, 49].
배너 광고 자동 생성: ComfyUI API를 Python과 연동하여 입력 이미지와 텍스트를 변경하며 대량의 광고 소재를 생성하는 실제 사례가 보고되었다 [50].
Mystic 파이프라인 배포:pipeline.yaml과 new_pipeline.py를 사용하여 텍스트-비디오 워크플로우를 서버리스 엔드포인트로 배포하는 구조가 상세히 기술되었다 [51-53].
✅ 검증 상태 및 신뢰도
상태: draft
검증 단계: conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능)
출처 신뢰도: B (Official Documentation / Primary Source via NotebookLM)
중복 검사 결과: 신규 생성 (New discovery)
📝 변경 이력 (Change history)
2026-05-20: Initial draft generated via Datacollector_MAC P-Reinforce engine.
koriweb
a3f63e56e2