2nd/10_Wiki/Topics/Comfyui/API Format (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-format-(workflow_api.json)	API Format (workflow_api.json)	10_Wiki/Topics	draft	conceptual		Backend Format API JSON		B	0.85	2026-05-19	2026-05-19			research Comfyui workflow json 생성 방법 API	NotebookLM Synthesis	comfyui-workflow-to-api-converter-endpoint/README.md comfy_api_simplified ComfyUI-to-Python-Extension Mystic pipeline code Replicate any-comfyui-workflow

API Format (workflow_api.json)

🎯 한 줄 통찰 (One-line insight)

UI 메타데이터를 제거하고 실행에 필수적인 노드 로직과 데이터 흐름만을 압축하여 서버 측 프로그래밍 및 /prompt 엔드포인트 실행에 최적화된 데이터 규격 [1, 2].

🧠 핵심 개념 (Core concepts)

• 실행 최적화 (Execution-centric): 시각적 배치 정보가 아닌 백엔드 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프만 포함함 [1, 3].
• UI 메타데이터 제거 (Metadata Stripping): 노드 위치(pos), 크기(size), 그룹, 색상 등 사용자 인터페이스와 관련된 모든 정보를 삭제하여 파일 크기를 경량화함 [1, 2, 4].
• 내장형 링크 참조 (Embedded Linkage): 별도의 링크 객체 배열 대신 노드 입력(inputs) 내에 소스 노드 ID와 출력 슬롯 인덱스를 직접 포함하는 구조를 가짐 [1, 5].
• 개발자 모드 의존성 (Dev Mode Dependency): 표준 환경에서는 숨겨져 있으며, 설정에서 'Dev mode Options'를 활성화해야만 생성 및 내보내기가 가능함 [6-8].

🧩 추출된 패턴 (Extracted patterns)

• 노드 식별 패턴: 각 노드는 숫자 문자열(예: "5", "6") 형태의 고유 키를 가지며, 이는 그래프 내에서 기능적 매핑을 위한 식별자로 사용됨 [3, 9, 10].
• 데이터 연결 패턴: 특정 노드의 입력 필드에 [노드ID, 출력슬롯번호] 형태의 리스트(예: [11, 12])를 할당하여 노드 간의 데이터 흐름을 정의함 [5].
• 직렬화 구조: 루트 레벨에서 노드 ID를 키로 하고, 그 값으로 class_type과 inputs를 포함하는 단일 JSON 객체 구조를 유지함 [10, 13].

📖 세부 내용 (Details)

1. 포맷의 정의와 목적

API 포맷(workflow_api.json)은 ComfyUI 백엔드 엔진이 직접 해석할 수 있는 **평탄화된 실행 그래프(flattened execution graph)**입니다 [6]. 주로 외부 애플리케이션 통합, 자동화 스크립트 실행, 서버리스 배포 환경에서 프롬프트를 큐(queue)에 추가할 때 사용됩니다 [1, 9].

2. 기술적 구성 요소

• 구조적 차이: 프론트엔드 포맷(workflow.json)이 Litegraph 표준을 따르며 시각적 가독성을 중시하는 반면, API 포맷은 백엔드 엔진의 /prompt 엔드포인트 사양에 맞춰 설계되었습니다 [1, 9].
• 노드 정의: 각 노드 객체는 해당 노드의 클래스 이름을 나타내는 class_type과 실제 파라미터 및 연결 정보를 담은 inputs 딕셔너리로 구성됩니다 [2, 10].
• 연결 방식: 프론트엔드 포맷의 links 배열이 제거되고, 모든 연결 정보가 inputs 내에 직접 주입됩니다. 예를 들어 CLIP 텍스트 인코딩 노드의 clip 입력값은 연결된 소스 노드 정보를 리스트 형태로 보유합니다 [5].

3. 생성 및 변환 프로세스

• 수동 생성: 설정 메뉴에서 'Enable Dev mode Options'를 체크한 후, 제어판에 나타나는 'Save (API Format)' 버튼을 통해 추출합니다 [7, 8, 14].
• 프로그래밍 방식 변환: comfyui-workflow-to-api-converter-endpoint와 같은 커스텀 노드를 사용하면 클라이언트 측 자바스크립트 로직 없이 서버 측에서 직접 프론트엔드 형식을 API 형식으로 변환할 수 있습니다 [15, 16].

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

• 가역성 문제 (Fragility): API 포맷은 실행에는 완벽하지만 시각적 정보가 없으므로, 이를 다시 UI로 드래그하여 로드하면 노드 배치가 깨지거나 그룹 정보가 사라진 '스켈레톤(skeleton)' 상태로 나타나 편집이 매우 어렵습니다 [17, 18].
• 버전 호환성: ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드 의존성이 있는 경우 실행 실패 가능성이 높습니다 [19, 20].

🛠️ 적용 사례 (Applied in summary)

• comfyui-workflow-to-api-converter-endpoint: 프론트엔드 워크플로우를 서버 측에서 API 포맷으로 즉시 변환하는 /workflow/convert 엔드포인트를 제공합니다 [15, 21].
• deimos-deimos/comfy_api_simplified: API 포맷 워크플로우를 로드하여 파이썬 딕셔너리로 다루고, 노드 제목(title)을 기준으로 파라미터를 수정하여 큐에 추가하는 기능을 구현합니다 [22, 23].
• Mystic & Replicate: 사용자 워크플로우를 서버리스 API로 배포할 때, 실행의 기본 단위로 workflow_api.json을 요구하거나 내부적으로 이를 사용하여 추론을 수행합니다 [14, 24, 25].
• ComfyUI-to-Python-Extension: API 포맷의 JSON을 입력받아 독립적으로 실행 가능한 파이썬 스크립트(.py)로 변환하는 기능을 수행합니다 [26, 27].

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual (실제 오픈소스 프로젝트 및 플랫폼에서 핵심 규격으로 활용됨)
• 출처 신뢰도: B (Official Documentation / GitHub Repository README 및 소스 코드 기반)
• 중복 검사 결과: 신규 생성 (New discovery)

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

상위/유사 개념

[아키텍처/기반 기술]

• Frontend Format (workflow.json)
  • 연결 이유: API 포맷과 대칭되는 시각적 편집용 데이터 규격임.
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 직렬화 시 UI 정보와 실행 정보의 분리 설계 방식.
• Directed Acyclic Graph (DAG)
  • 연결 이유: API 포맷은 노드와 링크로 구성된 추상화된 그래프 구조를 표현함.
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 의존성 및 실행 순서 결정 원리.

[구현/활용 도구]

• ComfyUI API
  • 연결 이유: API 포맷은 /prompt 엔드포인트 호출 시 전달되는 페이로드의 핵심 데이터임.
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 실제 서버 통신 및 작업 큐잉 프로세스.
• ComfyUI-to-Python-Extension
  • 연결 이유: API JSON을 파이썬 코드로 변환하여 독립 실행 환경을 구축함.
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 실제 실행 코드로 치환되는 매핑 원리.

심층 후속 질문 (Deeper Research Questions)

• 왜 ComfyUI는 시각적 정보와 실행 정보를 하나의 JSON에 통합하지 않고 두 가지 포맷으로 분리하여 관리하는가? [1]
• API 포맷에서 노드 ID가 문자열 형태의 숫자로 고정될 때, 워크플로우 편집 시 ID 충돌이나 누락을 방지하는 메커니즘은 무엇인가? [3, 28]
• comfyui-workflow-to-api-converter-endpoint는 클라이언트 측의 자바스크립트 변환 로직을 어떻게 파이썬 서버 측 로직으로 완벽하게 이식했는가? [15]
• 대규모 워크플로우(예: 200KB 이상)를 API 포맷으로 호출할 때 성능 저하나 데이터 누락이 발생할 가능성은 없는가? [16]
• object_info.json에 정의된 노드 스키마와 API 포맷의 inputs 데이터 구조 사이의 유효성 검사 과정은 어떻게 이루어지는가? [13]

실무 적용 맥락 (Practical Application Contexts)

• Implementation: 파이썬의 json 라이브러리를 사용하여 API JSON을 로드하고, 특정 노드 ID의 inputs 값을 변경하여 동적 프롬프트를 생성할 수 있음 [10, 29].
• System Design: 프론트엔드 수정을 최소화하면서 백엔드 자동화를 구축하기 위해 서버 측에서 변환 엔드포인트를 활용하는 캐싱 전략을 수립할 수 있음 [17].
• Operation / Maintenance: 커스텀 노드 업데이트 시 API 포맷 내의 class_type 명칭이 변경되지 않았는지 확인하여 서비스 중단을 방지해야 함 [19].
• Learning Path: 노드 기반 UI에 익숙해진 후, 개발자 모드를 통해 추출된 API JSON의 구조를 분석하여 프로그래밍 방식의 자동화 단계로 진입함 [6].

인접 주변 주제 (Adjacent Topics)

• Model Hashing (SHA-256)
  • 확장 방향: API JSON 내의 모델 파일 이름 불일치 문제를 해결하기 위한 고유 식별 기술 조사 [30].
• Serverless Deployment
  • 확장 방향: API 포맷을 클라우드 환경(Replicate, Mystic)에 배포하여 확장성 있는 AI 서비스를 구축하는 방법 [14, 31].

📝 변경 이력 (Change history)

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