2nd/10_Wiki/Topics/Comfyui/Workflow.api.json (Backend Format).md

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

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
workflow.api.json-(backend-format)	Workflow.api.json (Backend Format)	10_Wiki/Topics	draft	conceptual		API Format Backend JSON workflow_api.json		B	0.85	2026-05-20	2026-05-20			research Comfyui workflow json 생성 방법	NotebookLM Synthesis	Mystic Pipeline Replicate (fofr/any-comfyui-workflow) ComfyUI-to-Python-Extension comfyui-workflow-to-api-converter-endpoint

Workflow.api.json (Backend Format)

🎯 한 줄 통찰 (One-line insight)

비주얼 메타데이터를 배제하고 노드 실행 로직에만 집중하여 서버측 자동화와 프로그래밍적 실행을 가능케 하는 최적화된 데이터 포맷 [1-3].

🧠 핵심 개념 (Core concepts)

• 실행 그래프 (Execution Graph): UI 관련 데이터(좌표, 크기, 그룹 등)를 제거하고 백엔드 엔진이 프롬프트를 실행하는 데 필요한 필수 로직만 남긴 스트림라인화된 구조 [1, 4].
• 임베디드 참조 (Embedded References): 링크 정보가 별도의 객체가 아니라 노드 입력(inputs) 필드 내에 소스 노드 ID와 출력 슬롯 인덱스의 리스트(예: [node_id, slot_index]) 형태로 직접 포함됨 [1, 2, 5].
• 딕셔너리 구조 (Dictionary Mapping): 노드 ID를 최상위 키로 사용하며, 각 값은 class_type과 inputs를 포함하는 객체로 구성된 단일 JSON 객체 형식 [6, 7].
• 개발자 모드 의존성 (Developer Mode Dependency): 표준 웹 UI에서는 숨겨져 있으며, 설정에서 'Enable Dev mode Options'를 활성화해야만 'Save (API Format)' 메뉴가 노출됨 [8-11].

🧩 추출된 패턴 (Extracted patterns)

• UI 데이터 스트리핑 (UI Data Stripping): 캔버스 레이아웃 정보를 삭제함으로써 파일 크기를 축소하고 API 호출의 효율성을 극대화하는 설계 패턴 [1, 2, 4].
• 노드 ID 키잉 (Node ID Keying): 숫자 문자열(예: "5", "37")을 키로 사용하여 유연한 그래프 트래버스 및 특정 노드 파라미터의 동적 오버라이드를 지원 [6, 7, 12].
• 입력값 치환 (Input Value Substitution): Python 등의 언어에서 JSON을 로드한 후 특정 노드 ID의 inputs 필드를 직접 수정하여 시드, 프롬프트, 이미지 경로 등을 변경하는 방식의 자동화 패턴 [6, 12, 13].

📖 세부 내용 (Details)

형식적 특성 및 구조 Workflow API JSON은 Litegraph 표준을 따르는 프런트엔드 형식(workflow.json)과 달리 ComfyUI 백엔드의 /prompt 엔드포인트와 직접 통신하기 위해 설계되었습니다 [1, 2]. 파일 내부의 각 항목은 고유한 노드 식별자를 키로 하며, 해당 노드가 어떤 클래스(class_type)인지와 어떤 입력값(inputs)을 사용하는지를 명시합니다 [4, 7]. 이때 입력값에는 위젯의 직접적인 값뿐만 아니라 다른 노드로부터 오는 연결 정보도 포함됩니다 [5].

생성 및 추출 방법

• GUI 내보내기: ComfyUI 설정 메뉴(톱니바퀴 아이콘)에서 'Enable Dev mode Options'를 체크한 후 사이드바 메뉴에 나타나는 'Save (API Format)' 버튼을 클릭하여 생성합니다 [8-11].
• 이미지 메타데이터: ComfyUI가 생성한 PNG 파일의 tEXt 또는 zTXt 청크에는 프런트엔드 워크플로우와 함께 'prompt'라는 이름으로 API 포맷의 JSON이 포함되어 자동 저장됩니다 [14, 15].
• 서버측 변환: comfyui-workflow-to-api-converter-endpoint와 같은 커스텀 노드를 사용하면 클라이언트 측의 자바스크립트 로직 없이도 서버에서 직접 일반 JSON을 API 포맷으로 변환할 수 있습니다 [16, 17].

활용 시나리오 이 포맷은 주로 외부 애플리케이션 통합에 사용됩니다. 예를 들어 Python 스크립트에서 워크플로우 템플릿을 로드하고 특정 노드의 텍스트 입력을 변경한 후 ComfyUI 서버에 큐잉하거나, Replicate와 같은 클라우드 환경에서 워크플로우를 실행하는 데 필수적입니다 [6, 12, 18, 19].

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

• 가독성 vs 효율성: API 포맷은 파일 크기가 작고 처리가 빠르지만, UI로 다시 드래그 앤 드롭했을 때 시각적 구조(노드 위치, 그룹화 등)가 복원되지 않는 "뼈대만 남은(skeleton)" 상태가 됩니다 [1, 20].
• 노드 ID의 취약성: 워크플로우를 UI에서 편집하면 노드 ID가 변경될 수 있으며, 이로 인해 특정 ID를 하드코딩한 자동화 스크립트가 깨질 위험이 존재합니다 [6, 21]. 이를 해결하기 위해 노드 타이틀 기반 접근 방식이 대안으로 제시되기도 합니다 [21, 22].

🛠️ 적용 사례 (Applied in summary)

• Mystic Deployment: pipeline.yaml과 함께 new_pipeline.py에서 API JSON을 로드하여 입력 프롬프트를 주입하고 서버를 실행하는 구조로 적용됨 [23, 24].
• Replicate API: fofr/any-comfyui-workflow 모델을 통해 API JSON 블롭을 전달받아 이미지를 생성하는 상용 서비스에 적용 [18, 25].
• ComfyUI-to-Python-Extension: workflow_api.json 파일을 입력받아 독립 실행 가능한 .py 스크립트로 변환하는 CLI 도구에서 핵심 데이터로 사용됨 [26, 27].
• Workflow Converter: 서버측 /workflow/convert 엔드포인트를 통해 비 API 워크플로우를 API 포맷으로 실시간 변환하여 Unity 기반 AI 도구 등에서 활용 [16, 17].

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual (실제 적용 사례 다수 확인됨)
• 출처 신뢰도: B (Official Documentation / RunComfy & Replicate API Docs / GitHub Repository READMEs)
• 중복 검사 결과: 신규 생성 (New discovery)

📝 변경 이력 (Change history)

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