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

Workflow API JSON

🎯 한 줄 통찰 (One-line insight)

Workflow API JSON은 시각적 메타데이터를 제거하고 노드 간의 순수 실행 로직과 연결성만을 최적화하여 제공하는 ComfyUI의 서버 측 실행 인터페이스용 핵심 데이터 규격이다 [1, 2].

🧠 핵심 개념 (Core concepts)

• 백엔드 실행 최적화 (Backend Optimization): 프론트엔드용 시각적 정보(위치, 크기, 색상)를 제외하고 오직 /prompt 엔드포인트 실행에 필요한 데이터만 포함한다 [1-3].
• 노드-슬롯 연결성 (Node-Slot Connectivity): 별도의 연결 객체 대신 노드 입력(inputs) 내에 직접 [원본 노드 ID, 출력 슬롯 인덱스] 형식으로 연결 정보를 임베딩한다 [1, 4, 5].
• 고유 식별자 체계 (Unique ID System): 각 노드는 고유한 숫자형 문자열 키(예: "5", "6")로 식별되며, 이는 실행 그래프 내에서 데이터 흐름을 추적하는 기준이 된다 [1, 3, 6].
• 직렬화 유연성 (Serialization Flexibility): 사람이 읽을 수 있는 JSON 형식을 취하며, 대규모 모델 가중치와 별개로 워크플로우 로직의 배포, 버전 관리 및 자동화를 가능하게 한다 [7-9].

🧩 추출된 패턴 (Extracted patterns)

• UI 메타데이터 스트리핑 (Metadata Stripping): 시각적 편집용 workflow.json에서 API 호출용 workflow_api.json으로 전환 시 pos, size, groups와 같은 필드를 제거하여 파일 크기를 축소하고 처리 효율을 높인다 [1, 2, 5].
• 실행 모델 인버전 (Execution Model Inversion): 엔진이 'Save Image'와 같은 출력 노드에서 역방향으로 그래프를 탐색하여 필수 종속성만 실행하고 불필요한 노드는 무시하는 구조를 취한다 [10].
• 입력 데이터 인젝션 (Input Injection): 자동화 시 JSON 내의 특정 노드 ID를 찾아 시드(seed), 프롬프트(prompt), 또는 Base64 인코딩된 이미지 데이터를 동적으로 교체하여 실행한다 [6, 11-13].

📖 세부 내용 (Details)

ComfyUI의 워크플로우 직렬화 형식은 크게 프론트엔드 포맷과 백엔드(API) 포맷으로 이분화된다 [1, 2, 14]. API JSON은 서버 측 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프를 나타내며, Litegraph 표준을 따르는 프론트엔드 포맷과 달리 매우 간결한 구조를 갖는다 [1, 3, 15].

• 생성 방법: 사용자는 설정 메뉴에서 "Dev mode Options"를 활성화해야 하며, 이후 제어판에 나타나는 "Save (API Format)" 또는 "Export (API)" 버튼을 통해 이 파일을 생성할 수 있다 [16-20].
• 구조적 특징: 루트 키는 노드 ID이며, 각 값은 class_type과 inputs를 포함하는 객체이다 [6, 20]. 예를 들어, 특정 노드의 입력 필드에 [ "20", 1 ]과 같은 배열이 있다면 이는 20번 노드의 2번 슬롯(인덱스 1) 출력이 연결되었음을 의미한다 [4].
• 메타데이터 임베딩: ComfyUI에서 생성된 PNG 또는 WebP 이미지에는 프론트엔드 워크플로우와 API 프롬프트(JSON 형식)가 모두 메타데이터(tEXt 또는 zTXt 청크)로 저장되어 있어, 이미지 자체를 인터페이스로 드래그하여 로직을 복구할 수 있다 [21-24].
• 프로그래밍 방식의 조작: 파이썬의 json 라이브러리를 사용하여 딕셔너리 구조를 직접 수정하거나, comfy_api_simplified와 같은 래퍼 라이브러리를 통해 노드 제목 기반으로 파라미터를 동적으로 변경하여 대량의 이미지를 자동 생성할 수 있다 [6, 25-27].

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

• 가독성 vs 편집성: API 포맷은 실행에는 효율적이나, 시각적 정보가 결여되어 있어 다시 ComfyUI 인터페이스로 불러올 경우 노드들이 겹쳐 보이거나 구조 파악이 어려운 '스켈레톤' 상태가 된다 [28-30].
• 파일 포맷 호환성: ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON 파일이 최신 버전에서 제대로 작동하지 않을 수 있는 호환성 문제가 존재한다 [31, 32].
• 커스텀 노드 의존성: JSON 자체에는 로직만 포함되므로, 워크플로우 생성자가 사용한 동일한 커스텀 노드가 로컬 환경에 설치되어 있지 않으면 'Red Box' 오류가 발생하며 실행이 불가능하다 [33, 34].

🛠️ 적용 사례 (Applied in summary)

• comfyui-workflow-to-api-converter-endpoint: 클라이언트 사이드 JS 로직을 파이썬으로 변환하여 서버 측에서 일반 워크플로우를 API 포맷으로 즉시 변환하는 엔드포인트를 제공한다 [28, 35].
• ComfyUI-to-Python-Extension: .json 워크플로우를 독립 실행 가능한 .py 스크립트로 변환하여 헤드리스(headless) 환경에서 실행할 수 있게 한다 [25, 36].
• ComfyUI-WorkflowGenerator: LLM(Qwen2.5 등)을 사용하여 자연어 설명을 실행 가능한 API JSON 그래프로 합성하고 유효성을 검증한다 [37-39].
• fofr/any-comfyui-workflow (Replicate): 클라우드 환경에서 JSON 블롭(blob)을 입력받아 API를 통해 워크플로우를 실행하고 결과를 반환한다 [40, 41].

✅ 검증 상태 및 신뢰도

• 상태: draft
• 검증 단계: conceptual (공식 문서 및 오픈소스 프로젝트 코드를 통해 데이터 규격 및 생성 방식 확인됨) [42, 43]
• 출처 신뢰도: B (Official Documentation / GitHub Repository / Expert Tutorial)
• 중복 검사 결과: 신규 생성 (New discovery)

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

상위/유사 개념

[아키텍처/기반 기술]

• Litegraph Standard
  • 연결 이유: ComfyUI 프론트엔드 JSON이 시각적 표현을 위해 채택한 기반 표준임 [1, 15].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: API 포맷으로 전환 시 제거되는 UI 메타데이터의 구조적 근거 [1, 2].
• Directed Acyclic Graph (DAG)
  • 연결 이유: ComfyUI 워크플로우의 근본적인 데이터 흐름 구조임 [7, 44].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 연결성과 실행 순서가 결정되는 논리적 원리 [7, 10].

[구현/활용 도구]

• ComfyUI Manager
  • 연결 이유: JSON 로드 시 발생하는 누락된 노드 및 모델 문제를 해결하는 필수 도구임 [33, 34, 45].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 워크플로우 배포 시 발생하는 의존성 관리 전략 [34, 46].
• /prompt endpoint
  • 연결 이유: API 포맷 JSON이 최종적으로 전송되어 처리되는 목적지임 [2, 16, 28].
  • 이 개념을 통해 더 깊게 이해할 수 있는 부분: 클라이언트-서버 간의 실제 통신 메커니즘 [12, 13].

심층 후속 질문 (Deeper Research Questions)

• API JSON 내에서 링크 정보를 별도 배열이 아닌 노드 입력(inputs) 내에 직접 임베딩하는 방식이 실행 효율성에 미치는 영향은 무엇인가? [1, 4]
• LLM 기반의 워크플로우 생성 모델은 학습 데이터 이후에 출시된 새로운 커스텀 노드의 I/O 스키마를 어떻게 동적으로 학습하고 반영할 수 있는가? [44, 47, 48]
• object_info.json을 활용하여 동적으로 생성된 API JSON의 유효성을 런타임에 검증하는 구체적인 알고리즘은 어떻게 설계되는가? [20, 49]
• 실행 모델 인버전(Execution Model Inversion) 과정에서 조건부 분기나 반복 루프가 포함된 복잡한 그래프의 종속성을 어떻게 추적하는가? [10]
• 모델 해싱(Model Hashing)을 통해 하드코딩된 파일 경로 문제를 해결할 때, 서로 다른 머신 간의 모델 버전 일관성을 보장하는 방법은 무엇인가? [32, 46]

실무 적용 맥락 (Practical Application Contexts)

• Implementation: 배너 광고 자동 생성 시스템 구축 시, 템플릿 JSON의 특정 노드(예: CLIPTextEncode)를 파이썬 스크립트로 수정하여 자동화할 수 있음 [12, 50].
• System Design: 서버리스 환경(Mystic, Replicate 등)에서 워크플로우를 배포할 때 UI 정보를 제거한 최적화된 API JSON을 기본 실행 단위로 설정함 [5, 19, 51].
• Operation / Maintenance: comfyui-workflow-to-api-converter-endpoint를 사용하여 프론트엔드 워크플로우만 관리하고 실행 직전에 API 포맷으로 변환함으로써 관리 포인트의 이원화를 방지함 [29, 35].
• Learning Path: 초보자는 시각적 그래프를 통해 로직을 이해하고, 숙련자는 개발자 모드를 통해 추출된 JSON의 노드 ID와 파라미터 구조를 분석하여 코딩 방식의 제어로 전이함 [52-54].

인접 주변 주제 (Adjacent Topics)

• Base64 Image Encoding
  • 확장 방향: API 요청 시 로컬 파일 경로 대신 이미지 데이터를 JSON에 직접 포함하는 기술적 구현 방법 [11, 13].
• RAG (Retrieval-Augmented Generation)
  • 확장 방향: 정적 모델의 한계를 극복하기 위해 실시간 노드 라이브러리를 검색하여 워크플로우를 생성하는 차세대 AI 에이전트 설계 [44].

📝 변경 이력 (Change history)

• 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Based on 18 sources) [1-200]