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

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

# [[API Format (workflow_api.json)]]

## 🎯 한 줄 통찰 (One-line insight)
UI 메타데이터를 제거하고 실행에 필수적인 노드 로직과 데이터 흐름만을 압축하여 서버 측 프로그래밍 및 `/prompt` 엔드포인트 실행에 최적화된 데이터 규격 [1, 2].

## 🧠 핵심 개념 (Core concepts)
- **실행 최적화 (Execution-centric):** 시각적 배치 정보가 아닌 백엔드 엔진이 프롬프트를 실행하는 데 필요한 최소한의 논리 그래프만 포함함 [1, 3].
- **UI 메타데이터 제거 (Metadata Stripping):** 노드 위치(pos), 크기(size), 그룹, 색상 등 사용자 인터페이스와 관련된 모든 정보를 삭제하여 파일 크기를 경량화함 [1, 2, 4].
- **내장형 링크 참조 (Embedded Linkage):** 별도의 링크 객체 배열 대신 노드 입력(inputs) 내에 소스 노드 ID와 출력 슬롯 인덱스를 직접 포함하는 구조를 가짐 [1, 5].
- **개발자 모드 의존성 (Dev Mode Dependency):** 표준 환경에서는 숨겨져 있으며, 설정에서 'Dev mode Options'를 활성화해야만 생성 및 내보내기가 가능함 [6-8].

## 🧩 추출된 패턴 (Extracted patterns)
- **노드 식별 패턴:** 각 노드는 숫자 문자열(예: "5", "6") 형태의 고유 키를 가지며, 이는 그래프 내에서 기능적 매핑을 위한 식별자로 사용됨 [3, 9, 10].
- **데이터 연결 패턴:** 특정 노드의 입력 필드에 `[노드ID, 출력슬롯번호]` 형태의 리스트(예: `[11, 12]`)를 할당하여 노드 간의 데이터 흐름을 정의함 [5].
- **직렬화 구조:** 루트 레벨에서 노드 ID를 키로 하고, 그 값으로 `class_type`과 `inputs`를 포함하는 단일 JSON 객체 구조를 유지함 [10, 13].

## 📖 세부 내용 (Details)
### 1. 포맷의 정의와 목적
API 포맷(`workflow_api.json`)은 ComfyUI 백엔드 엔진이 직접 해석할 수 있는 **평탄화된 실행 그래프(flattened execution graph)**입니다 [6]. 주로 외부 애플리케이션 통합, 자동화 스크립트 실행, 서버리스 배포 환경에서 프롬프트를 큐(queue)에 추가할 때 사용됩니다 [1, 9].

### 2. 기술적 구성 요소
- **구조적 차이:** 프론트엔드 포맷(`workflow.json`)이 Litegraph 표준을 따르며 시각적 가독성을 중시하는 반면, API 포맷은 백엔드 엔진의 `/prompt` 엔드포인트 사양에 맞춰 설계되었습니다 [1, 9].
- **노드 정의:** 각 노드 객체는 해당 노드의 클래스 이름을 나타내는 `class_type`과 실제 파라미터 및 연결 정보를 담은 `inputs` 딕셔너리로 구성됩니다 [2, 10].
- **연결 방식:** 프론트엔드 포맷의 `links` 배열이 제거되고, 모든 연결 정보가 `inputs` 내에 직접 주입됩니다. 예를 들어 CLIP 텍스트 인코딩 노드의 `clip` 입력값은 연결된 소스 노드 정보를 리스트 형태로 보유합니다 [5].

### 3. 생성 및 변환 프로세스
- **수동 생성:** 설정 메뉴에서 'Enable Dev mode Options'를 체크한 후, 제어판에 나타나는 **'Save (API Format)'** 버튼을 통해 추출합니다 [7, 8, 14].
- **프로그래밍 방식 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 클라이언트 측 자바스크립트 로직 없이 서버 측에서 직접 프론트엔드 형식을 API 형식으로 변환할 수 있습니다 [15, 16].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **가역성 문제 (Fragility):** API 포맷은 실행에는 완벽하지만 시각적 정보가 없으므로, 이를 다시 UI로 드래그하여 로드하면 노드 배치가 깨지거나 그룹 정보가 사라진 '스켈레톤(skeleton)' 상태로 나타나 편집이 매우 어렵습니다 [17, 18].
- **버전 호환성:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드 의존성이 있는 경우 실행 실패 가능성이 높습니다 [19, 20].

## 🛠️ 적용 사례 (Applied in summary)
- **comfyui-workflow-to-api-converter-endpoint:** 프론트엔드 워크플로우를 서버 측에서 API 포맷으로 즉시 변환하는 `/workflow/convert` 엔드포인트를 제공합니다 [15, 21].
- **deimos-deimos/comfy_api_simplified:** API 포맷 워크플로우를 로드하여 파이썬 딕셔너리로 다루고, 노드 제목(title)을 기준으로 파라미터를 수정하여 큐에 추가하는 기능을 구현합니다 [22, 23].
- **Mystic & Replicate:** 사용자 워크플로우를 서버리스 API로 배포할 때, 실행의 기본 단위로 `workflow_api.json`을 요구하거나 내부적으로 이를 사용하여 추론을 수행합니다 [14, 24, 25].
- **ComfyUI-to-Python-Extension:** API 포맷의 JSON을 입력받아 독립적으로 실행 가능한 파이썬 스크립트(`.py`)로 변환하는 기능을 수행합니다 [26, 27].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 오픈소스 프로젝트 및 플랫폼에서 핵심 규격으로 활용됨)
- **출처 신뢰도:** B (Official Documentation / GitHub Repository README 및 소스 코드 기반)
- **중복 검사 결과:** 신규 생성 (New discovery)


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

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Frontend Format (workflow.json)]]
  - 연결 이유: API 포맷과 대칭되는 시각적 편집용 데이터 규격임.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 데이터 직렬화 시 UI 정보와 실행 정보의 분리 설계 방식.
- [[Directed Acyclic Graph (DAG)]]
  - 연결 이유: API 포맷은 노드와 링크로 구성된 추상화된 그래프 구조를 표현함.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 간 의존성 및 실행 순서 결정 원리.

#### [구현/활용 도구]
- [[ComfyUI API]]
  - 연결 이유: API 포맷은 `/prompt` 엔드포인트 호출 시 전달되는 페이로드의 핵심 데이터임.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 실제 서버 통신 및 작업 큐잉 프로세스.
- [[ComfyUI-to-Python-Extension]]
  - 연결 이유: API JSON을 파이썬 코드로 변환하여 독립 실행 환경을 구축함.
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 데이터가 실제 실행 코드로 치환되는 매핑 원리.

### 심층 후속 질문 (Deeper Research Questions)
- 왜 ComfyUI는 시각적 정보와 실행 정보를 하나의 JSON에 통합하지 않고 두 가지 포맷으로 분리하여 관리하는가? [1]
- API 포맷에서 노드 ID가 문자열 형태의 숫자로 고정될 때, 워크플로우 편집 시 ID 충돌이나 누락을 방지하는 메커니즘은 무엇인가? [3, 28]
- `comfyui-workflow-to-api-converter-endpoint`는 클라이언트 측의 자바스크립트 변환 로직을 어떻게 파이썬 서버 측 로직으로 완벽하게 이식했는가? [15]
- 대규모 워크플로우(예: 200KB 이상)를 API 포맷으로 호출할 때 성능 저하나 데이터 누락이 발생할 가능성은 없는가? [16]
- `object_info.json`에 정의된 노드 스키마와 API 포맷의 `inputs` 데이터 구조 사이의 유효성 검사 과정은 어떻게 이루어지는가? [13]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 파이썬의 `json` 라이브러리를 사용하여 API JSON을 로드하고, 특정 노드 ID의 `inputs` 값을 변경하여 동적 프롬프트를 생성할 수 있음 [10, 29].
- **System Design:** 프론트엔드 수정을 최소화하면서 백엔드 자동화를 구축하기 위해 서버 측에서 변환 엔드포인트를 활용하는 캐싱 전략을 수립할 수 있음 [17].
- **Operation / Maintenance:** 커스텀 노드 업데이트 시 API 포맷 내의 `class_type` 명칭이 변경되지 않았는지 확인하여 서비스 중단을 방지해야 함 [19].
- **Learning Path:** 노드 기반 UI에 익숙해진 후, 개발자 모드를 통해 추출된 API JSON의 구조를 분석하여 프로그래밍 방식의 자동화 단계로 진입함 [6].

### 인접 주변 주제 (Adjacent Topics)
- [[Model Hashing (SHA-256)]]
  - 확장 방향: API JSON 내의 모델 파일 이름 불일치 문제를 해결하기 위한 고유 식별 기술 조사 [30].
- [[Serverless Deployment]]
  - 확장 방향: API 포맷을 클라우드 환경(Replicate, Mystic)에 배포하여 확장성 있는 AI 서비스를 구축하는 방법 [14, 31].

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