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

API JSON (workflow_api.json)

🎯 한 줄 통찰 (One-line insight)

API JSON은 ComfyUI의 시각적 메타데이터를 제거하고 백엔드 엔진의 즉각적인 실행을 위해 최적화된 경량화된 실행 그래프 형식이다 [1], [2], [3].

🧠 핵심 개념 (Core concepts)

• 백엔드 실행 그래프 (Backend Execution Graph): 노드 위치, 크기, 색상 등의 UI 정보를 배제하고 오직 노드 유형, 입력값, 연결 관계만을 포함하는 실행 전용 데이터 구조이다 [1], [4], [3].
• 직접 링크 임베딩 (Direct Link Embedding): 연결 정보가 별도의 객체 배열로 관리되지 않고, 각 노드의 입력 필드 내에 소스 노드 ID와 출력 슬롯 번호의 참조([node_id, slot_index]) 형태로 직접 포함된다 [1], [2], [5].
• 개발자 모드 의존성 (Dev Mode Dependency): 표준 내보내기(Save)와 달리, ComfyUI 설정에서 'Enable Dev mode Options'를 활성화해야만 생성 및 수동 추출이 가능하다 [6], [7], [8], [9].
• 프로그래밍적 제어 (Programmatic Control): 텍스트 프롬프트, 시드(Seed) 등 위젯 값을 노드 ID를 통해 직접 수정할 수 있어 외부 애플리케이션 및 스크립트와의 자동화 연동에 핵심적인 역할을 한다 [10], [11], [12].

🧩 추출된 패턴 (Extracted patterns)

• UI-Stripping 패턴: 시각적 요소(Litegraph 메타데이터)를 삭제하여 파일 크기를 축소하고 데이터 파싱 속도를 향상시킨다 [1], [13], [3].
• ID 기반 맵 구조: 전체 JSON 구조가 노드 ID를 키(Key)로 하고 노드 정의(Inputs, Class Type)를 값(Value)으로 하는 단일 딕셔너리 형태를 취한다 [10], [14].
• 입력 우선주의 (Execution Model Inversion): 백엔드 엔진이 출력 노드(Save Image 등)로부터 역추적하여 필요한 노드만 실행하도록 하는 구조적 기반을 제공한다 [15].

📖 세부 내용 (Details)

• 데이터 구조 및 구성 요소: API JSON의 각 노드 객체는 해당 노드의 클래스 이름을 나타내는 class_type과 노드에 전달될 데이터인 inputs를 필수적으로 포함한다 [10], [3]. inputs 내에는 사용자가 직접 입력한 위젯 값과 다른 노드에서 전달되는 링크 정보가 공존한다 [5].
• 프론트엔드 형식과의 차이: 시각적 편집을 위한 workflow.json은 노드 위치(pos), 크기(size), 그룹 정보 등을 포함하여 다시 불러왔을 때 캔버스를 재구성할 수 있게 하지만, API JSON은 이를 모두 제거하여 "스켈레톤(skeleton)" 상태의 데이터만 남긴다 [1], [13], [16].
• 생성 및 변환 프로세스:
  • 수동 생성: ComfyUI 설정 메뉴의 기어 아이콘을 클릭하여 'Enable Dev mode Options'를 활성화한 후, 메뉴 상단에 나타나는 'Save (API Format)' 버튼을 사용한다 [6], [7], [8].
  • 자동 추출: ComfyUI에서 생성된 PNG/WebP 파일의 메타데이터(tEXt 또는 zTXt 청크)에서 prompt 태그를 통해 API 형식을 추출할 수 있다 [17], [18], [19].
  • 서버측 변환: comfyui-workflow-to-api-converter-endpoint와 같은 커스텀 노드를 사용하여 일반 워크플로우 JSON을 API 형식으로 실시간 변환하여 /prompt 엔드포인트로 전송할 수 있다 [20], [21].
• 실행 환경에서의 활용: API JSON은 파이썬 스크립트에서 urllib이나 requests를 통해 ComfyUI 서버의 /prompt 경로로 POST 요청을 보낼 때 페이로드(Payload)로 사용된다 [11], [22]. 또한 Replicate와 같은 클라우드 플랫폼에서 서버리스 엔드포인트를 구동하는 기본 사양으로 채택된다 [23], [24], [4].

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

• 가역성 상실: API JSON을 ComfyUI 캔버스로 다시 드래그하면 시각적 레이아웃 정보가 없기 때문에 모든 노드가 겹쳐서 나타나거나 그룹 정보가 유실되어 수동 편집이 매우 어렵다 [16]. 따라서 편집용 'Full Workflow'를 항상 별도로 보관하는 것이 권장된다 [16].
• 버전 호환성 주의: ComfyUI의 잦은 업데이트로 인해 이전 버전에서 생성된 API JSON이 최신 백엔드 엔진에서 유효하지 않은 노드 클래스나 입력 방식을 참조할 경우 실행 오류가 발생할 수 있다 [25], [26].

🛠️ 적용 사례 (Applied in summary)

• SethRobinson/comfyui-workflow-to-api-converter-endpoint: 클라이언트 측의 자바스크립트 변환 로직을 파이썬으로 구현하여, 서버 측에서 비-API 워크플로우를 API 형식으로 즉시 변환해주는 커스텀 노드 (Commit: bc85382) [27], [20].
• fofr/any-comfyui-workflow (Replicate): 사용자가 제공한 API JSON 블롭(blob)을 해석하여 이미지 및 비디오를 생성하는 범용 API 모델 [23], [24].
• Mystic Pipeline: new_pipeline.py 스크립트를 통해 API JSON 워크플로우를 로드하고 입력 프롬프트를 동적으로 주입하여 서버리스 엔드포인트로 배포하는 구조 [9], [28].
• ComfyUI-to-Python-Extension: API JSON 파일을 입력받아 독립적으로 실행 가능한 파이썬 스크립트(.py)로 변환하는 도구 [29], [30].

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual (실제 적용 사례 다수 발견으로 검증 가능성 높음)
• 출처 신뢰도: B (공식 문서 및 주요 오픈소스 프로젝트 기술 사양 기반)
• 중복 검사 결과: 신규 생성 (New discovery)

📝 변경 이력 (Change history)

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