2nd/10_Wiki/Topics/Comfyui/API 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-format	API Format	10_Wiki/Topics	draft	conceptual		API JSON workflow_api.json Backend Format		B	0.90	2026-05-19	2026-05-19			research Comfyui workflow json 생성 방법 API JSON Automation	NotebookLM Synthesis	comfyui-workflow-to-api-converter-endpoint deimos-deimos/comfy_api_simplified pydn/ComfyUI-to-Python-Extension	bc85382

API Format

🎯 한 줄 통찰 (One-line insight)

ComfyUI API 포맷은 시각적 메타데이터를 제거하고 노드 간의 논리적 연결과 입력값만을 보존하여 서버 측 실행 및 프로그래밍 방식의 자동화에 최적화된 경량화된 실행 그래프이다 [1-3].

🧠 핵심 개념 (Core concepts)

• 실행 그래프 (Execution Graph): UI 좌표, 노드 크기, 그룹화 정보 등 시각적 요소를 배제하고 백엔드 엔진이 프롬프트를 실행하는 데 필요한 순수 논리 구조만 포함한다 [1, 3, 4].
• 임베디드 링크 (Embedded Links): 별도의 링크 객체 배열을 사용하는 대신, 노드의 입력 필드(inputs) 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: [5, 6])하여 연결을 정의한다 [1, 2, 7].
• 기능적 키 매핑 (Functional Key Mapping): JSON 객체의 최상위 키가 노드 ID(문자열)이며, 각 값은 class_type과 inputs를 포함하는 딕셔너리 구조를 가진다 [8-10].
• 개발자 모드 활성화 (Dev Mode Requirement): 일반적인 저장 방식과 달리 ComfyUI 설정에서 'Enable Dev mode Options'를 활성화해야만 내보낼 수 있는 특수 포맷이다 [11-14].

🧩 추출된 패턴 (Extracted patterns)

• UI/백엔드 이원화 패턴: 사용자 인터페이스용 workflow.json과 실행 전용 workflow_api.json을 분리하여 편집 효율성과 실행 속도를 동시에 확보한다 [1, 2, 15].
• 메타데이터 캡슐화: PNG 이미지의 tEXt 또는 zTXt 청크에 API 포맷(prompt) 데이터를 포함시켜 이미지 자체가 실행 가능한 소스 코드 역할을 하도록 설계한다 [16, 17].
• 직접 딕셔너리 조작 패턴: 개발자가 JSON을 로드하여 특정 노드 ID의 inputs 값을 파이썬 등으로 수정 후 /prompt 엔드포인트에 전송하는 동적 제어 방식을 지원한다 [8, 10, 18].

📖 세부 내용 (Details)

ComfyUI의 API 포맷은 주로 workflow_api.json 파일로 알려져 있으며, 서버리스 API 호출이나 외부 애플리케이션 통합 시 핵심적인 역할을 한다 [2, 15]. 이 포맷은 Litegraph 표준을 따르는 프론트엔드 포맷과 달리, 백엔드 엔진이 즉시 해석할 수 있도록 평탄화(Flattened)된 구조를 가진다 [1, 11].

구조적으로 API 포맷은 노드 ID를 키로 사용하는 단일 JSON 객체이다 [9]. 각 노드 정의에는 해당 노드의 클래스 이름인 class_type과 위젯 값 및 링크 정보를 포함하는 inputs 딕셔너리가 들어간다 [3, 8]. 예를 들어, CLIPTextEncode 노드의 경우 텍스트 입력값과 함께 연결된 CLIP 모델의 노드 정보를 [노드ID, 슬롯번호] 형태의 배열로 보유한다 [7, 10].

이 포맷은 데이터 용량이 작고 효율적이지만, 다시 ComfyUI 인터페이스로 드래그했을 때 시각적 레이아웃 정보가 없어 노드들이 겹치거나 연결 구조를 파악하기 힘든 '스켈레톤(Skeleton)' 상태로 로드된다는 특징이 있다 [19, 20]. 따라서 실무에서는 시각적 편집용 원본 워크플로를 별도로 보관하는 것이 권장된다 [20]. 또한, 최근에는 시각적 포맷을 API 포맷으로 실시간 변환해주는 서버측 엔드포인트 도구들이 개발되어 이 단점을 보완하고 있다 [19, 21].

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

• 가독성 vs 실행력: API 포맷은 인간이 읽기에 간결하지만, 시각적 정보가 결여되어 있어 복잡한 워크플로를 이 포맷만으로 수동 편집하기에는 한계가 있다 [17, 20].
• 버전 호환성: ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON API 포맷이 최신 서버 환경에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [22].
• 데이터 유실 위험: 표준 이미지 편집기나 소셜 미디어를 거칠 경우 PNG 메타데이터에 포함된 API 포맷 정보가 삭제될 수 있어 전송 시 주의가 필요하다 [16].

🛠️ 적용 사례 (Applied in summary)

• comfyui-workflow-to-api-converter-endpoint: 프론트엔드 워크플로를 API 포맷으로 변환하는 서버측 /workflow/convert 엔드포인트를 구현하였다 [19].
  • Git 커밋: bc85382 (콤보 위젯 값의 대소문자 정규화 수정 포함) [23, 24].
• deimos-deimos/comfy_api_simplified: 노드 제목(Title)을 기준으로 API 포맷의 파라미터를 수정하고 큐에 등록하는 파이썬 래퍼 기능을 제공한다 [25-27].
• pydn/ComfyUI-to-Python-Extension: 저장된 API 포맷 JSON을 독립 실행 가능한 .py 스크립트로 변환하는 CLI 기능을 포함한다 [28-30].
• Mystic (Pipeline AI): 사용자의 API JSON을 파이썬 엔드포인트 내에 주입하여 서버리스 환경에서 실행하는 템플릿을 제공한다 [14, 31].

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual
• 출처 신뢰도: B (공식 문서 및 오픈소스 프로젝트 코드 기반) [23, 32]
• 중복 검사 결과: 신규 생성

🔗 관련 문서 링크 (Related document links)

상위/유사 개념

[아키텍처/기반 기술]

• Frontend Format
  • 연결 이유: API 포맷과 대조되는 시각적 편집용 데이터 구조임. [1, 2]
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 분리 전략 및 Litegraph 표준의 한계. [1, 33]
• Directed Acyclic Graph (DAG)
  • 연결 이유: ComfyUI 워크플로가 직렬화되는 근본적인 논리 구조임. [34]
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 실행 순서와 데이터 흐름 제어 원리. [34, 35]

[구현/활용 도구]

• ComfyUI-to-Python-Extension
  • 연결 이유: API JSON을 파이썬 코드로 변환하는 직접적인 도구임. [28]
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 객체가 실제 파이썬 함수 호출로 매핑되는 과정. [29, 36]
• ComfyUI Manager
  • 연결 이유: API 포맷 로드 시 발생하는 커스텀 노드 누락 문제를 해결하는 필수 도구임. [37, 38]
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 종속성 관리 및 class_type 기반의 노드 복구 메커니즘. [37, 39]

심층 후속 질문 (Deeper Research Questions)

• API 포맷에서 노드 ID가 단순한 숫자 문자열을 넘어 기능적 키(Functional Key)로 작동할 때, 대규모 워크플로에서 ID 충돌을 방지하는 내부 메커니즘은 무엇인가? [1, 2]
• workflow_api.json에 포함된 _meta 필드는 실행 엔진에서 어떤 구체적인 역할을 수행하며, 필수 요소인가? [9]
• 서브그래프(Subgraph)가 중첩된 워크플로를 API 포맷으로 내보낼 때, 내부 링크 ID와 외부 링크 ID의 충돌을 처리하는 알고리즘은 어떻게 설계되어 있는가? [40]
• API 포맷 내의 inputs 필드에서 위젯 값(widgets_values)과 동적 링크 연결을 구분하여 처리하는 구문 분석 로직은 무엇인가? [7, 41]
• exiftool과 같은 외부 CLI 도구를 사용하여 PNG에서 API JSON을 추출할 때, 메타데이터 손상을 복구하거나 검증할 수 있는 표준 스키마가 존재하는가? [42, 43]

실무 적용 맥락 (Practical Application Contexts)

• Implementation: 파이썬 json 라이브러리를 사용하여 API JSON 파일을 로드하고, 특정 노드 ID의 입력값을 수정한 뒤 서버의 /prompt 엔드포인트로 POST 요청을 보내 자동화를 구현한다 [8, 10, 18].
• System Design: 프론트엔드 편집 도구와 백엔드 실행기를 분리하여, 사용자는 웹 UI에서 편집하고 실제 운영 환경에서는 경량화된 API JSON만 사용하여 리소스를 최적화한다 [1, 44].
• Operation / Maintenance: API JSON에는 모델 체크포인트의 이름이 하드코딩되므로, 서버 간 모델 공유 시 파일명 불일치 문제를 해결하기 위해 모델 해싱(SHA-256) 기술과 함께 운용한다 [45, 46].
• Learning Path: 먼저 GUI에서 워크플로를 완성한 후, 개발자 모드를 통해 API 포맷을 내보내고 그 구조를 분석하여 프로그래밍 방식의 제어 단계로 넘어가는 것이 표준 학습 경로이다 [14, 47].

인접 주변 주제 (Adjacent Topics)

• Node Definitions
  • 확장 방향: API 포맷 내 class_type이 참조하는 각 노드의 입력/출력 타입 정의 연구. [43]
• Execution Model Inversion
  • 확장 방향: API JSON 전체 중 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리 이해. [32, 48]

📝 변경 이력 (Change history)

• 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 기반 소스 18개 종합 분석 완료. [1-186]