2nd/10_Wiki/Topics/Comfyui/API JSON (Backend Format).md

---
id: api-json-(backend-format)
title: "API JSON (Backend Format)"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["workflow_api.json", "Backend Format"]
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: ["workflow_api.json", "/workflow/convert", "new_pipeline.py", "SaveImageWebsocket"]
github_commit: "bc85382"
---

# [[API JSON (Backend Format)]]

## 🎯 한 줄 통찰 (One-line insight)
API JSON은 UI 메타데이터를 배제하고 실행 로직과 데이터 흐름만을 압축하여 서버 측 실행 및 프로그래밍 방식의 자동화에 최적화된 백엔드 전용 워크플로우 규격이다 [1, 2].

## 🧠 핵심 개념 (Core concepts)
1. **실행 중심 그래프 (Execution Graph):** 위치, 크기, 색상 등 시각적 요소를 제거하고 엔진이 노드를 처리하는 데 필요한 핵심 논리 구조만 포함한다 [1, 3, 4].
2. **참조 기반 노드 연결:** 링크 객체를 별도로 관리하는 대신 노드 입력(`inputs`) 필드 내에 소스 노드 ID와 출력 슬롯 인덱스를 직접 배열(예: `[node_id, slot_index]`) 형태로 임베딩한다 [1, 5, 6].
3. **데이터 경량화:** 시각적 메타데이터 제거를 통해 프런트엔드 JSON보다 파일 크기가 훨씬 작으며, 네트워크 전송 및 API 호출 페이로드로 사용하기에 적합하다 [2, 7, 8].
4. **개발자 모드 활성화:** 표준 저장 방식과 달리 ComfyUI 설정에서 'Dev mode'를 명시적으로 활성화해야만 생성 및 내보내기가 가능하다 [9-11].

## 🧩 추출된 패턴 (Extracted patterns)
- **노드 ID 키 매핑 패턴:** JSON의 루트 레벨에서 각 노드의 고유 숫자 ID(문자열 형태)를 키값으로 사용하며, 그 내부에 `class_type`과 `inputs`를 정의한다 [3, 12, 13].
- **입출력 노드 최적화:** API 활용 시 이미지를 웹소켓으로 직접 수신하기 위해 `SaveImageWebsocket` 노드를 사용하거나, `Load Image (Base64)`를 통해 이미지 데이터를 직접 주입하는 구조를 취한다 [14].
- **역방향 그래프 탐색:** 백엔드 엔진은 API JSON을 실행할 때 출력 노드(예: Save Image)부터 역방향으로 탐색하여 결과 도출에 필요한 종속 노드만 식별하고 실행한다 [15].

## 📖 세부 내용 (Details)
API JSON(일반적으로 `workflow_api.json`으로 명명)은 ComfyUI의 백엔드 엔진과 직접 통신하는 언어 역할을 수행한다 [1, 2, 16].

- **프런트엔드 포맷과의 차별성:** 표준 `workflow.json`이 인간의 가독성과 편집 편의성을 위해 노드 좌표(`pos`), 크기(`size`), 그룹, 위젯 상태(`flags`) 등을 포함하는 것과 달리, API 포맷은 이러한 정보를 모두 폐기하고 오직 실행에 필요한 데이터만 남긴다 [1-3, 17, 18].
- **내부 구조 분석:** 
    - **`class_type`:** 노드 레지스트리에 등록된 실제 Python 클래스 이름을 참조한다 [4, 12, 19].
    - **`inputs`:** 위젯 값(텍스트, 숫자 등)과 다른 노드로부터 오는 동적 링크 정보를 모두 포함한다 [4, 5].
- **생성 프로세스:** 
    1. ComfyUI 설정 아이콘을 클릭한다 [9, 10, 20].
    2. 'Enable Dev mode Options' 체크박스를 활성화한다 [9-11].
    3. 메인 메뉴에 새로 나타난 'Save (API Format)' 버튼을 클릭하여 다운로드한다 [10, 11, 21].
- **이미지 메타데이터와의 관계:** ComfyUI에서 생성된 PNG 파일의 메타데이터에는 프런트엔드 포맷(workflow)과 API 포맷(prompt) 데이터가 동시에 저장되어 있어, 이미지만으로도 시각적 복구와 프로그래밍 방식의 재실행이 모두 가능하다 [8, 22, 23].
- **자동화 및 확장:** Python의 `json` 라이브러리를 사용하여 노드 ID를 기반으로 프롬프트나 시드 값을 동적으로 변경한 후 서버의 `/prompt` 엔드포인트로 전송하여 대량의 이미지를 생성할 수 있다 [6, 12, 14].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **가역성의 한계:** API JSON을 다시 ComfyUI 인터페이스로 드래그하여 불러올 경우, 시각적 위치 정보가 없기 때문에 노드들이 모두 겹쳐서 나타나는 '스켈레톤(skeleton)' 상태가 된다 [24]. 따라서 재편집을 위해서는 반드시 원본 프런트엔드 포맷을 별도로 보관해야 한다 [24].
- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드 의존성이 있는 경우 더욱 빈번하게 발생한다 [25].

## 🛠️ 적용 사례 (Applied in summary)
- **RunComfy Serverless API:** `workflow_api.json`을 내부적으로 저장하여 서버리스 실행 시 베이스라인으로 활용하며, API 호출 시 입력값만 오버라이드한다 [4, 16].
- **Mystic Pipeline (`new_pipeline.py`):** Python SDK를 통해 ComfyUI 서버를 시작하고 API 포맷 JSON에 프롬프트를 주입하여 실행하는 템플릿에 적용됨 [26, 27].
- **ComfyUI Workflow Converter (`bc85382`):** `/workflow/convert` 엔드포인트를 통해 비 API 포맷(Frontend)을 실시간으로 API 포맷으로 변환하여 `/prompt` 엔드포인트에 즉시 사용할 수 있도록 지원 [28-30].
- **SaveImageWebsocket 노드:** API 환경에서 생성된 이미지를 파일 저장 대신 웹소켓을 통해 실시간 바이너리로 수신할 때 사용됨 [14].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능)
- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM)
- **중복 검사 결과:** 신규 생성 (New discovery)

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