2nd/10_Wiki/Comfyui/API JSON (workflow_api.json).md

---
id: api-json-(workflow_api.json)
title: "API JSON (workflow_api.json)"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["Backend Format", "API Format JSON", "Execution Graph"]
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 생성 방법", "API", "JSON"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["SethRobinson/comfyui-workflow-to-api-converter-endpoint", "fofr/any-comfyui-workflow", "Mystic Pipeline", "ComfyUI-to-Python-Extension"]
github_commit: "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.