2nd/10_Wiki/Comfyui/Workflow API JSON.md

---
id: workflow-api-json
title: "Workflow API JSON"
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.95
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: ["SethRobinson/comfyui-workflow-to-api-converter-endpoint", "pydn/ComfyUI-to-Python-Extension", "DanielPFlorian/ComfyUI-WorkflowGenerator", "deimos-deimos/comfy_api_simplified"]
github_commit: ""
---

# [[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]