2nd/10_Wiki/Topics/Comfyui/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
api-json-(backend-format)	API JSON (Backend Format)	10_Wiki/Topics	draft	conceptual		workflow_api.json Backend Format		B	0.85	2026-05-20	2026-05-20			research Comfyui workflow json 생성 방법	NotebookLM Synthesis	workflow_api.json /workflow/convert new_pipeline.py SaveImageWebsocket	bc85382

API JSON (Backend Format)

🎯 한 줄 통찰 (One-line insight)

API JSON은 UI 메타데이터를 배제하고 실행 로직과 데이터 흐름만을 압축하여 서버 측 실행 및 프로그래밍 방식의 자동화에 최적화된 백엔드 전용 워크플로우 규격이다 [1, 2].

🧠 핵심 개념 (Core concepts)

1. 실행 중심 그래프 (Execution Graph): 위치, 크기, 색상 등 시각적 요소를 제거하고 엔진이 노드를 처리하는 데 필요한 핵심 논리 구조만 포함한다 [1, 3, 4].
2. 참조 기반 노드 연결: 링크 객체를 별도로 관리하는 대신 노드 입력(inputs) 필드 내에 소스 노드 ID와 출력 슬롯 인덱스를 직접 배열(예: [node_id, slot_index]) 형태로 임베딩한다 [1, 5, 6].
3. 데이터 경량화: 시각적 메타데이터 제거를 통해 프런트엔드 JSON보다 파일 크기가 훨씬 작으며, 네트워크 전송 및 API 호출 페이로드로 사용하기에 적합하다 [2, 7, 8].
4. 개발자 모드 활성화: 표준 저장 방식과 달리 ComfyUI 설정에서 'Dev mode'를 명시적으로 활성화해야만 생성 및 내보내기가 가능하다 [9-11].

🧩 추출된 패턴 (Extracted patterns)

• 노드 ID 키 매핑 패턴: JSON의 루트 레벨에서 각 노드의 고유 숫자 ID(문자열 형태)를 키값으로 사용하며, 그 내부에 class_type과 inputs를 정의한다 [3, 12, 13].
• 입출력 노드 최적화: API 활용 시 이미지를 웹소켓으로 직접 수신하기 위해 SaveImageWebsocket 노드를 사용하거나, Load Image (Base64)를 통해 이미지 데이터를 직접 주입하는 구조를 취한다 [14].
• 역방향 그래프 탐색: 백엔드 엔진은 API JSON을 실행할 때 출력 노드(예: Save Image)부터 역방향으로 탐색하여 결과 도출에 필요한 종속 노드만 식별하고 실행한다 [15].

📖 세부 내용 (Details)

API JSON(일반적으로 workflow_api.json으로 명명)은 ComfyUI의 백엔드 엔진과 직접 통신하는 언어 역할을 수행한다 [1, 2, 16].

• 프런트엔드 포맷과의 차별성: 표준 workflow.json이 인간의 가독성과 편집 편의성을 위해 노드 좌표(pos), 크기(size), 그룹, 위젯 상태(flags) 등을 포함하는 것과 달리, API 포맷은 이러한 정보를 모두 폐기하고 오직 실행에 필요한 데이터만 남긴다 [1-3, 17, 18].
• 내부 구조 분석:
  • class_type: 노드 레지스트리에 등록된 실제 Python 클래스 이름을 참조한다 [4, 12, 19].
  • inputs: 위젯 값(텍스트, 숫자 등)과 다른 노드로부터 오는 동적 링크 정보를 모두 포함한다 [4, 5].
• 생성 프로세스:
  1. ComfyUI 설정 아이콘을 클릭한다 [9, 10, 20].
  2. 'Enable Dev mode Options' 체크박스를 활성화한다 [9-11].
  3. 메인 메뉴에 새로 나타난 'Save (API Format)' 버튼을 클릭하여 다운로드한다 [10, 11, 21].
• 이미지 메타데이터와의 관계: ComfyUI에서 생성된 PNG 파일의 메타데이터에는 프런트엔드 포맷(workflow)과 API 포맷(prompt) 데이터가 동시에 저장되어 있어, 이미지만으로도 시각적 복구와 프로그래밍 방식의 재실행이 모두 가능하다 [8, 22, 23].
• 자동화 및 확장: Python의 json 라이브러리를 사용하여 노드 ID를 기반으로 프롬프트나 시드 값을 동적으로 변경한 후 서버의 /prompt 엔드포인트로 전송하여 대량의 이미지를 생성할 수 있다 [6, 12, 14].

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

• 가역성의 한계: API JSON을 다시 ComfyUI 인터페이스로 드래그하여 불러올 경우, 시각적 위치 정보가 없기 때문에 노드들이 모두 겹쳐서 나타나는 '스켈레톤(skeleton)' 상태가 된다 [24]. 따라서 재편집을 위해서는 반드시 원본 프런트엔드 포맷을 별도로 보관해야 한다 [24].
• 버전 호환성 문제: ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드 의존성이 있는 경우 더욱 빈번하게 발생한다 [25].

🛠️ 적용 사례 (Applied in summary)

• RunComfy Serverless API: workflow_api.json을 내부적으로 저장하여 서버리스 실행 시 베이스라인으로 활용하며, API 호출 시 입력값만 오버라이드한다 [4, 16].
• Mystic Pipeline (new_pipeline.py): Python SDK를 통해 ComfyUI 서버를 시작하고 API 포맷 JSON에 프롬프트를 주입하여 실행하는 템플릿에 적용됨 [26, 27].
• ComfyUI Workflow Converter (bc85382): /workflow/convert 엔드포인트를 통해 비 API 포맷(Frontend)을 실시간으로 API 포맷으로 변환하여 /prompt 엔드포인트에 즉시 사용할 수 있도록 지원 [28-30].
• SaveImageWebsocket 노드: API 환경에서 생성된 이미지를 파일 저장 대신 웹소켓을 통해 실시간 바이너리로 수신할 때 사용됨 [14].

✅ 검증 상태 및 신뢰도

• 상태: 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.