2nd/10_Wiki/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 JSON", "Backend Format JSON"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["ComfyUI-WorkflowGenerator", "ComfyUI-to-Python-Extension", "comfyui-workflow-to-api-converter-endpoint", "comfy_api_simplified"]
github_commit: ""
---

# [[Workflow API JSON (Backend Format)]]

## 🎯 한 줄 통찰 (One-line insight)
시각적 레이아웃 정보를 제거하고 노드 간의 실행 로직과 데이터 흐름만을 정제하여, ComfyUI 백엔드 엔진의 `/prompt` 엔드포인트에서 즉각 실행 가능한 최적화된 그래프 데이터 형식이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **UI 메타데이터의 박리 (Stripping UI Metadata):** 노드 위치, 크기, 그룹화 정보, 색상 등 캔버스 시각화를 위한 모든 데이터를 제외하여 파일 크기를 축소하고 처리 효율성을 높인다 [1-4].
- **임베디드 링크 구조 (Embedded Link Representation):** 별도의 연결 객체 배열을 사용하는 대신, 노드 입력 필드 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: `[5, 6]`)하여 관계를 정의한다 [1, 2, 7, 8].
- **기능적 키 매핑 (Functional Key Mapping):** 각 노드는 고유한 문자열 키(ID)로 식별되며, `class_type`과 `inputs`를 핵심 속성으로 보유하여 백엔드 노드 레지스트리와 직접 매핑된다 [2, 9-11].

## 🧩 추출된 패턴 (Extracted patterns)
- **개발자 모드 전환 패턴:** 수동 생성 시 설정 메뉴에서 'Enable Dev mode Options'를 활성화하여 'Save (API Format)' 버튼을 노출시키는 것이 필수 절차이다 [3, 12-15].
- **동적 파라미터 주입 패턴:** 생성된 JSON 템플릿을 로드한 후, 특정 노드 ID의 `inputs` 딕셔너리에 접근하여 시드(Seed), 프롬프트, 이미지 경로 등을 프로그래밍 방식으로 수정하여 재전송한다 [9, 11, 16-18].
- **데이터 인라인화 (Self-containment):** 외부 파일 참조 대신 "Load Image (Base64)" 노드 등을 통해 이미지 데이터를 Base64 문자열로 JSON 내부에 직접 포함시켜 자가 포함된 요청을 구성한다 [19, 20].

## 📖 세부 내용 (Details)
Workflow API JSON은 ComfyUI의 두 가지 주요 직렬화 형식 중 하나로, 주로 **프로그램 방식의 실행 및 API 호출**을 위해 설계되었다 [1, 2]. 이 형식은 Litegraph 표준을 따르는 프런트엔드 형식(`workflow.json`)과 달리 백엔드 엔진이 프롬프트를 처리하기 위해 예상하는 평면화된 실행 그래프(Flattened execution graph)를 제공한다 [1, 12].

기술적으로 API JSON은 루트 키가 노드 ID이고 값이 노드 정의인 단일 JSON 객체 구조를 갖는다 [10]. 각 노드 정의에는 `class_type`, `inputs`, 그리고 선택적인 `_meta` 데이터가 포함된다 [10]. 연결(Link)은 입력 리스트 내에서 `[소스_노드_ID, 소스_슬롯_인덱스]` 형태의 배열로 표현되며, 이는 특정 슬롯(예: VAE Loader의 VAE 출력 슬롯)을 명확하게 지정하는 데 중요하다 [7, 8].

실행 시 ComfyUI 백엔드는 이 JSON을 수신하여 '실행 모델 역전(Execution Model Inversion)' 방식을 적용한다 [21]. 즉, 'Save Image'와 같은 출력 노드에서 시작하여 그래프를 역방향으로 추적하며 필요한 의존성만 식별하여 실행한다 [21]. 이 과정 덕분에 JSON 내에 실행과 무관한 노드가 포함되어 있어도 성능에 영향을 주지 않는다 [21]. 또한, API JSON은 모델 가중치와 독립적이므로 크기가 매우 작아 버전 관리와 아카이빙에 유리하다 [22, 23].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **가독성 및 편집성:** API JSON은 실행에는 최적화되어 있으나, ComfyUI UI로 다시 드래그 앤 드롭할 경우 노드 위치 정보 등이 없어 로직만 남은 '뼈대' 상태로 로드되어 시각적 편집이 어렵다는 단점이 지적된다 [24, 25].
- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 이전 버전의 API JSON 형식이 최신 버전의 백엔드 엔진에서 정상적으로 작동하지 않을 수 있는 호환성 문제가 존재한다 [26].
- **메타데이터 취약성:** PNG 이미지에 임베드된 API JSON 데이터는 이미지 편집기나 소셜 미디어 플랫폼을 거치면서 손실되기 쉽다 [27].

## 🛠️ 적용 사례 (Applied in summary)
- **comfyui-workflow-to-api-converter-endpoint:** 프런트엔드 포맷을 백엔드 API 포맷으로 서버 측에서 변환하는 `/workflow/convert` 엔드포인트를 제공한다 [28, 29].
- **ComfyUI-to-Python-Extension:** API 포맷의 JSON을 독립 실행 가능한 Python 스크립트로 변환하는 기능을 지원한다 [30, 31].
- **comfy_api_simplified:** 노드 타이틀을 기준으로 API JSON의 파라미터를 수정하고 큐에 추가할 수 있는 Python 래퍼 라이브러리이다 [16, 18].
- **Replicate 및 RunComfy 플랫폼:** 사용자가 업로드한 API JSON을 기반으로 서버리스 환경에서 워크플로를 실행하고 결과를 반환하는 시스템 아키텍처를 보유하고 있다 [4, 32, 33].

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


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

### 상위/유사 개념
#### [아키텍처 및 데이터 표준]
- [[Workflow JSON (Frontend Format)]]
  - 연결 이유: API JSON의 원형이 되는 시각적 작업 데이터 포맷이다 [1, 34].
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 데이터 유무에 따른 두 포맷 간의 구조적 차이와 변환 필요성 [2].
- [[Litegraph Standard]]
  - 연결 이유: ComfyUI 프런트엔드가 채택하고 있는 그래프 시각화 표준이다 [1, 34].

#### [구현 및 자동화 도구]
- [[ComfyUI API Integration]]
  - 연결 이유: API JSON이 실제로 활용되는 최종 목적지이다 [12, 35].
- [[ComfyUI Manager]]
  - 연결 이유: API JSON 로드 시 발생하는 커스텀 노드 의존성 문제를 해결하는 핵심 도구이다 [36, 37].

### 심층 후속 질문 (Deeper Research Questions)
- 시각적 레이아웃이 없는 API JSON을 다시 UI용 프런트엔드 JSON으로 복원할 때, 노드 배치 알고리즘은 어떻게 작동하는가?
- 노드 ID가 동적으로 변경될 수 있는 환경에서, 특정 노드를 타이틀(Title) 기반으로 안정적으로 식별하여 값을 수정하는 최적의 휴리스틱은 무엇인가? [16, 18]
- Execution Model Inversion 가이드에 명시된 백엔드 엔진의 노드 순회 알고리즘은 순환 참조를 어떻게 방지하는가? [21]
- 이미지 내 메타데이터에 포함된 API JSON이 손실되었을 때, 픽셀 정보를 분석하여 워크플로를 추론하는 기술적 가능성이 존재하는가?
- 대규모 배치 처리 환경에서 API JSON의 `_meta` 필드를 활용하여 실행 로그와 결과를 추적하는 방법은 무엇인가? [10]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 자동화 스크립트 작성 시 `json` 라이브러리를 사용해 API JSON의 특정 노드 `inputs` 값을 덮어씌워 서버에 POST 요청을 보낸다 [9, 20].
- **System Design:** 서버리스 AI 서비스 구축 시, 사용자의 의도를 LLM으로 해석하여 API JSON 구조를 동적으로 생성하는 파이프라인을 설계한다 [38-40].
- **Operation / Maintenance:** ComfyUI Manager를 통해 JSON 내에 정의된 `class_type`을 기반으로 누락된 커스텀 노드를 자동 설치하여 환경을 동기화한다 [36, 41].
- **Learning Path:** 기본 텍스트-투-이미지 워크플로를 API 형식으로 내보내고, Python에서 시드값을 바꿔가며 실행해보는 것부터 시작한다 [20, 42].

### 인접 주변 주제 (Adjacent Topics)
- [[Model Hashing (SHA-256)]]
  - 확장 방향: JSON 내 모델 파일 이름 불일치 문제를 해결하기 위한 모델 고유 식별 기술 [43].
- [[Base64 Image Encoding]]
  - 확장 방향: API 요청 시 파일 업로드 없이 데이터를 JSON에 직렬화하여 전달하는 방식 [19, 20].

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. (Source references 29, 30, 32, 37, 38, 42, 43, 44, 45, 46, 71, 85, 86, 116, 124, 143, 144, 151, 152, 161, 162, 174, 192, 196 등 활용) [1-4, 7-16, 18-21, 24, 28, 30, 31, 36, 43]