2nd/10_Wiki/Topics/Comfyui/Workflow.api.json (Backend Format).md

---
id: workflow.api.json-(backend-format)
title: "Workflow.api.json (Backend Format)"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["API Format", "Backend JSON", "workflow_api.json"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["Mystic Pipeline", "Replicate (fofr/any-comfyui-workflow)", "ComfyUI-to-Python-Extension", "comfyui-workflow-to-api-converter-endpoint"]
github_commit: ""
---

# [[Workflow.api.json (Backend Format)]]

## 🎯 한 줄 통찰 (One-line insight)
비주얼 메타데이터를 배제하고 노드 실행 로직에만 집중하여 서버측 자동화와 프로그래밍적 실행을 가능케 하는 최적화된 데이터 포맷 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **실행 그래프 (Execution Graph):** UI 관련 데이터(좌표, 크기, 그룹 등)를 제거하고 백엔드 엔진이 프롬프트를 실행하는 데 필요한 필수 로직만 남긴 스트림라인화된 구조 [1, 4].
- **임베디드 참조 (Embedded References):** 링크 정보가 별도의 객체가 아니라 노드 입력(inputs) 필드 내에 소스 노드 ID와 출력 슬롯 인덱스의 리스트(예: `[node_id, slot_index]`) 형태로 직접 포함됨 [1, 2, 5].
- **딕셔너리 구조 (Dictionary Mapping):** 노드 ID를 최상위 키로 사용하며, 각 값은 `class_type`과 `inputs`를 포함하는 객체로 구성된 단일 JSON 객체 형식 [6, 7].
- **개발자 모드 의존성 (Developer Mode Dependency):** 표준 웹 UI에서는 숨겨져 있으며, 설정에서 'Enable Dev mode Options'를 활성화해야만 'Save (API Format)' 메뉴가 노출됨 [8-11].

## 🧩 추출된 패턴 (Extracted patterns)
- **UI 데이터 스트리핑 (UI Data Stripping):** 캔버스 레이아웃 정보를 삭제함으로써 파일 크기를 축소하고 API 호출의 효율성을 극대화하는 설계 패턴 [1, 2, 4].
- **노드 ID 키잉 (Node ID Keying):** 숫자 문자열(예: "5", "37")을 키로 사용하여 유연한 그래프 트래버스 및 특정 노드 파라미터의 동적 오버라이드를 지원 [6, 7, 12].
- **입력값 치환 (Input Value Substitution):** Python 등의 언어에서 JSON을 로드한 후 특정 노드 ID의 `inputs` 필드를 직접 수정하여 시드, 프롬프트, 이미지 경로 등을 변경하는 방식의 자동화 패턴 [6, 12, 13].

## 📖 세부 내용 (Details)
**형식적 특성 및 구조**
Workflow API JSON은 Litegraph 표준을 따르는 프런트엔드 형식(`workflow.json`)과 달리 ComfyUI 백엔드의 `/prompt` 엔드포인트와 직접 통신하기 위해 설계되었습니다 [1, 2]. 파일 내부의 각 항목은 고유한 노드 식별자를 키로 하며, 해당 노드가 어떤 클래스(`class_type`)인지와 어떤 입력값(`inputs`)을 사용하는지를 명시합니다 [4, 7]. 이때 입력값에는 위젯의 직접적인 값뿐만 아니라 다른 노드로부터 오는 연결 정보도 포함됩니다 [5].

**생성 및 추출 방법**
- **GUI 내보내기:** ComfyUI 설정 메뉴(톱니바퀴 아이콘)에서 'Enable Dev mode Options'를 체크한 후 사이드바 메뉴에 나타나는 'Save (API Format)' 버튼을 클릭하여 생성합니다 [8-11].
- **이미지 메타데이터:** ComfyUI가 생성한 PNG 파일의 `tEXt` 또는 `zTXt` 청크에는 프런트엔드 워크플로우와 함께 'prompt'라는 이름으로 API 포맷의 JSON이 포함되어 자동 저장됩니다 [14, 15].
- **서버측 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 클라이언트 측의 자바스크립트 로직 없이도 서버에서 직접 일반 JSON을 API 포맷으로 변환할 수 있습니다 [16, 17].

**활용 시나리오**
이 포맷은 주로 외부 애플리케이션 통합에 사용됩니다. 예를 들어 Python 스크립트에서 워크플로우 템플릿을 로드하고 특정 노드의 텍스트 입력을 변경한 후 ComfyUI 서버에 큐잉하거나, Replicate와 같은 클라우드 환경에서 워크플로우를 실행하는 데 필수적입니다 [6, 12, 18, 19].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **가독성 vs 효율성:** API 포맷은 파일 크기가 작고 처리가 빠르지만, UI로 다시 드래그 앤 드롭했을 때 시각적 구조(노드 위치, 그룹화 등)가 복원되지 않는 "뼈대만 남은(skeleton)" 상태가 됩니다 [1, 20].
- **노드 ID의 취약성:** 워크플로우를 UI에서 편집하면 노드 ID가 변경될 수 있으며, 이로 인해 특정 ID를 하드코딩한 자동화 스크립트가 깨질 위험이 존재합니다 [6, 21]. 이를 해결하기 위해 노드 타이틀 기반 접근 방식이 대안으로 제시되기도 합니다 [21, 22].

## 🛠️ 적용 사례 (Applied in summary)
- **Mystic Deployment:** `pipeline.yaml`과 함께 `new_pipeline.py`에서 API JSON을 로드하여 입력 프롬프트를 주입하고 서버를 실행하는 구조로 적용됨 [23, 24].
- **Replicate API:** `fofr/any-comfyui-workflow` 모델을 통해 API JSON 블롭을 전달받아 이미지를 생성하는 상용 서비스에 적용 [18, 25].
- **ComfyUI-to-Python-Extension:** `workflow_api.json` 파일을 입력받아 독립 실행 가능한 `.py` 스크립트로 변환하는 CLI 도구에서 핵심 데이터로 사용됨 [26, 27].
- **Workflow Converter:** 서버측 `/workflow/convert` 엔드포인트를 통해 비 API 워크플로우를 API 포맷으로 실시간 변환하여 Unity 기반 AI 도구 등에서 활용 [16, 17].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 다수 확인됨)
- **출처 신뢰도:** B (Official Documentation / RunComfy & Replicate API Docs / GitHub Repository READMEs)
- **중복 검사 결과:** 신규 생성 (New discovery)

## 📝 변경 이력 (Change history)
- 2026-05-20: Initial draft generated via Datacollector_MAC P-Reinforce engine.