Files

T

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

5.9 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

workflow_api.json

🎯 한 줄 통찰 (One-line insight)

workflow_api.json은 UI 메타데이터를 제거하고 노드 간의 기능적 연결성만을 추출하여 ComfyUI 백엔드 엔진이 즉시 실행할 수 있도록 최적화된 직렬화된 실행 그래프이다 [1-3].

🧠 핵심 개념 (Core concepts)

백엔드/API 포맷 (Backend/API Format): 시각적 요소(위치, 크기, 그룹 등)를 배제하고 서버 사이드 처리 및 프로그램 기반 자동화에 최적화된 포맷이다 [1, 3].
평탄화된 그래프 (Flattened Execution Graph): 링크가 별도의 연결 객체가 아닌 노드 입력 내부에 직접 참조(Origin Node ID 및 Output Slot) 형태로 포함된 구조이다 [1, 3, 4].
개발자 모드 종속성 (Dev Mode Dependency): 표준 내보내기 기능과 달리, 설정 메뉴에서 'Dev mode Options'를 활성화해야만 생성이 가능한 특수 포맷이다 [5-7].
/prompt 엔드포인트 호환성: ComfyUI 서버의 API 엔드포인트에 직접 전달하여 워크플로우를 실행하기 위한 표준 데이터 구조로 사용된다 [2, 8, 9].

🧩 추출된 패턴 (Extracted patterns)

포맷 분화 (Schema Bifurcation): 사용자 상호작용을 위한 'Frontend JSON(workflow.json)'과 실행을 위한 'API JSON(workflow_api.json)'을 철저히 분리하여 운영 효율성을 극대화한다 [1, 2, 10].
노드 식별 기반 접근: 각 노드는 고유한 숫자형 키(String ID)로 식별되며, 이를 통해 외부 스크립트에서 특정 노드의 입력을 동적으로 수정할 수 있다 [11, 12].
역방향 의존성 탐색 (Execution Model Inversion): 엔진이 출력 노드(Save Image 등)로부터 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 실행하는 구조를 지원한다 [13].

📖 세부 내용 (Details)

데이터 구조 및 속성
workflow_api.json은 루트 레벨의 키가 노드 ID(문자열)인 단일 JSON 객체 구조를 가진다 [14]. 각 노드 정의에는 class_type(노드 클래스 이름)과 inputs(위젯 값 및 타 노드 출력에 대한 연결 정보)가 포함되며, 선택적으로 _meta 필드가 존재할 수 있다 [11, 14]. 링크 표현 방식은 [node_id, output_slot_index] 형태의 배열로 입력 필드에 직접 삽입된다 [3, 15].

생성 및 추출 프로세스

GUI 내보내기: 설정 메뉴의 톱니바퀴 아이콘을 통해 'Enable Dev mode Options'를 활성화한 후, 제어판에 나타나는 'Save (API Format)' 또는 'Export (API)' 버튼을 사용하여 생성한다 [6, 7, 14, 16].
이미지 메타데이터 추출: ComfyUI에서 생성된 PNG 파일의 tEXt 또는 zTXt 청크에는 워크플로우(Frontend)와 프롬프트(API) 데이터가 함께 저장되며, exiftool이나 전문 추출 도구를 통해 이를 복구할 수 있다 [17-20].
서버 사이드 변환: comfyui-workflow-to-api-converter-endpoint와 같은 커스텀 노드를 사용하면 일반 워크플로우 포맷을 실시간으로 API 포맷으로 변환하는 엔드포인트를 구축할 수 있다 [9, 21].

프로그래밍적 활용
이 포맷은 Python의 json 라이브러리를 통해 딕셔너리 형태로 로드되어 씨드(seed), 프롬프트 텍스트, 노이즈 강도 등의 파라미터를 동적으로 변경하는 데 사용된다 [11, 22]. Replicate, Mystic, RunComfy 등 클라우드 API 서비스는 이 포맷을 기반으로 워크플로우를 서버리스 함수나 컨테이너화된 서비스로 배포한다 [3, 23, 24].

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

정보 손실의 비가역성: API 포맷을 다시 ComfyUI 캔버스로 불러올 경우, UI 메타데이터가 삭제되어 있기 때문에 노드들이 겹쳐 보이거나 그룹 정보가 사라진 '뼈대(skeleton)' 상태로 복원되는 한계가 있다 [9, 25].
버전 호환성 문제: ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드의 클래스 타입 변경에 취약하다 [26, 27].

🛠️ 적용 사례 (Applied in summary)

comfyui-workflow-to-api-converter-endpoint: 클라이언트 측의 자바스크립트 변환 로직을 파이썬으로 구현하여 /workflow/convert 엔드포인트를 제공함 [9, 28]. (Git Commit: bc85382)
ComfyUI-to-Python-Extension: workflow_api.json 입력을 받아 실행 가능한 .py 스크립트로 변환하는 기능을 지원함 [29, 30].
Mystic Pipeline Deployment: new_pipeline.py 스크립트 내에서 API 포맷 JSON을 로드하여 입력 프롬프트를 주입하고 실행하는 템플릿 구조에 적용됨 [31, 32].
Replicate fofr/any-comfyui-workflow: API JSON 블롭을 입력받아 이미지/비디오를 생성하는 범용 워크플로우 모델의 핵심 입력 데이터로 활용됨 [23, 33].

✅ 검증 상태 및 신뢰도

상태: draft
검증 단계: conceptual (실제 적용 사례 다수 발견으로 검증 가능)
출처 신뢰도: B (공식 문서 및 개발자 가이드 기반 합성)
중복 검사 결과: 신규 생성 (New discovery)

📝 변경 이력 (Change history)

2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.

5.9 KiB Raw Blame History