---
id: api-format
title: "API Format"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["API JSON", "workflow_api.json", "Backend Format"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.90
created_at: 2026-05-19
updated_at: 2026-05-19
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법", "API", "JSON", "Automation"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["comfyui-workflow-to-api-converter-endpoint", "deimos-deimos/comfy_api_simplified", "pydn/ComfyUI-to-Python-Extension"]
github_commit: "bc85382"
---

# [[API Format]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI API 포맷은 시각적 메타데이터를 제거하고 노드 간의 논리적 연결과 입력값만을 보존하여 서버 측 실행 및 프로그래밍 방식의 자동화에 최적화된 경량화된 실행 그래프이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **실행 그래프 (Execution Graph):** UI 좌표, 노드 크기, 그룹화 정보 등 시각적 요소를 배제하고 백엔드 엔진이 프롬프트를 실행하는 데 필요한 순수 논리 구조만 포함한다 [1, 3, 4].
- **임베디드 링크 (Embedded Links):** 별도의 링크 객체 배열을 사용하는 대신, 노드의 입력 필드(`inputs`) 내에 소스 노드 ID와 출력 슬롯 번호를 직접 참조(예: `[5, 6]`)하여 연결을 정의한다 [1, 2, 7].
- **기능적 키 매핑 (Functional Key Mapping):** JSON 객체의 최상위 키가 노드 ID(문자열)이며, 각 값은 `class_type`과 `inputs`를 포함하는 딕셔너리 구조를 가진다 [8-10].
- **개발자 모드 활성화 (Dev Mode Requirement):** 일반적인 저장 방식과 달리 ComfyUI 설정에서 'Enable Dev mode Options'를 활성화해야만 내보낼 수 있는 특수 포맷이다 [11-14].

## 🧩 추출된 패턴 (Extracted patterns)
- **UI/백엔드 이원화 패턴:** 사용자 인터페이스용 `workflow.json`과 실행 전용 `workflow_api.json`을 분리하여 편집 효율성과 실행 속도를 동시에 확보한다 [1, 2, 15].
- **메타데이터 캡슐화:** PNG 이미지의 `tEXt` 또는 `zTXt` 청크에 API 포맷(prompt) 데이터를 포함시켜 이미지 자체가 실행 가능한 소스 코드 역할을 하도록 설계한다 [16, 17].
- **직접 딕셔너리 조작 패턴:** 개발자가 JSON을 로드하여 특정 노드 ID의 `inputs` 값을 파이썬 등으로 수정 후 `/prompt` 엔드포인트에 전송하는 동적 제어 방식을 지원한다 [8, 10, 18].

## 📖 세부 내용 (Details)
ComfyUI의 API 포맷은 주로 `workflow_api.json` 파일로 알려져 있으며, 서버리스 API 호출이나 외부 애플리케이션 통합 시 핵심적인 역할을 한다 [2, 15]. 이 포맷은 Litegraph 표준을 따르는 프론트엔드 포맷과 달리, 백엔드 엔진이 즉시 해석할 수 있도록 평탄화(Flattened)된 구조를 가진다 [1, 11]. 

구조적으로 API 포맷은 노드 ID를 키로 사용하는 단일 JSON 객체이다 [9]. 각 노드 정의에는 해당 노드의 클래스 이름인 `class_type`과 위젯 값 및 링크 정보를 포함하는 `inputs` 딕셔너리가 들어간다 [3, 8]. 예를 들어, `CLIPTextEncode` 노드의 경우 텍스트 입력값과 함께 연결된 CLIP 모델의 노드 정보를 `[노드ID, 슬롯번호]` 형태의 배열로 보유한다 [7, 10].

이 포맷은 데이터 용량이 작고 효율적이지만, 다시 ComfyUI 인터페이스로 드래그했을 때 시각적 레이아웃 정보가 없어 노드들이 겹치거나 연결 구조를 파악하기 힘든 '스켈레톤(Skeleton)' 상태로 로드된다는 특징이 있다 [19, 20]. 따라서 실무에서는 시각적 편집용 원본 워크플로를 별도로 보관하는 것이 권장된다 [20]. 또한, 최근에는 시각적 포맷을 API 포맷으로 실시간 변환해주는 서버측 엔드포인트 도구들이 개발되어 이 단점을 보완하고 있다 [19, 21].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **가독성 vs 실행력:** API 포맷은 인간이 읽기에 간결하지만, 시각적 정보가 결여되어 있어 복잡한 워크플로를 이 포맷만으로 수동 편집하기에는 한계가 있다 [17, 20].
- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 구버전의 JSON API 포맷이 최신 서버 환경에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [22].
- **데이터 유실 위험:** 표준 이미지 편집기나 소셜 미디어를 거칠 경우 PNG 메타데이터에 포함된 API 포맷 정보가 삭제될 수 있어 전송 시 주의가 필요하다 [16].

## 🛠️ 적용 사례 (Applied in summary)
- **comfyui-workflow-to-api-converter-endpoint:** 프론트엔드 워크플로를 API 포맷으로 변환하는 서버측 `/workflow/convert` 엔드포인트를 구현하였다 [19].
  - **Git 커밋:** `bc85382` (콤보 위젯 값의 대소문자 정규화 수정 포함) [23, 24].
- **deimos-deimos/comfy_api_simplified:** 노드 제목(Title)을 기준으로 API 포맷의 파라미터를 수정하고 큐에 등록하는 파이썬 래퍼 기능을 제공한다 [25-27].
- **pydn/ComfyUI-to-Python-Extension:** 저장된 API 포맷 JSON을 독립 실행 가능한 `.py` 스크립트로 변환하는 CLI 기능을 포함한다 [28-30].
- **Mystic (Pipeline AI):** 사용자의 API JSON을 파이썬 엔드포인트 내에 주입하여 서버리스 환경에서 실행하는 템플릿을 제공한다 [14, 31].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual
- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 코드 기반) [23, 32]
- **중복 검사 결과:** 신규 생성


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

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Frontend Format]]
  - 연결 이유: API 포맷과 대조되는 시각적 편집용 데이터 구조임. [1, 2]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 메타데이터 분리 전략 및 Litegraph 표준의 한계. [1, 33]
- [[Directed Acyclic Graph (DAG)]]
  - 연결 이유: ComfyUI 워크플로가 직렬화되는 근본적인 논리 구조임. [34]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 실행 순서와 데이터 흐름 제어 원리. [34, 35]

#### [구현/활용 도구]
- [[ComfyUI-to-Python-Extension]]
  - 연결 이유: API JSON을 파이썬 코드로 변환하는 직접적인 도구임. [28]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 객체가 실제 파이썬 함수 호출로 매핑되는 과정. [29, 36]
- [[ComfyUI Manager]]
  - 연결 이유: API 포맷 로드 시 발생하는 커스텀 노드 누락 문제를 해결하는 필수 도구임. [37, 38]
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 종속성 관리 및 `class_type` 기반의 노드 복구 메커니즘. [37, 39]

### 심층 후속 질문 (Deeper Research Questions)
- API 포맷에서 노드 ID가 단순한 숫자 문자열을 넘어 기능적 키(Functional Key)로 작동할 때, 대규모 워크플로에서 ID 충돌을 방지하는 내부 메커니즘은 무엇인가? [1, 2]
- `workflow_api.json`에 포함된 `_meta` 필드는 실행 엔진에서 어떤 구체적인 역할을 수행하며, 필수 요소인가? [9]
- 서브그래프(Subgraph)가 중첩된 워크플로를 API 포맷으로 내보낼 때, 내부 링크 ID와 외부 링크 ID의 충돌을 처리하는 알고리즘은 어떻게 설계되어 있는가? [40]
- API 포맷 내의 `inputs` 필드에서 위젯 값(`widgets_values`)과 동적 링크 연결을 구분하여 처리하는 구문 분석 로직은 무엇인가? [7, 41]
- `exiftool`과 같은 외부 CLI 도구를 사용하여 PNG에서 API JSON을 추출할 때, 메타데이터 손상을 복구하거나 검증할 수 있는 표준 스키마가 존재하는가? [42, 43]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** 파이썬 `json` 라이브러리를 사용하여 API JSON 파일을 로드하고, 특정 노드 ID의 입력값을 수정한 뒤 서버의 `/prompt` 엔드포인트로 POST 요청을 보내 자동화를 구현한다 [8, 10, 18].
- **System Design:** 프론트엔드 편집 도구와 백엔드 실행기를 분리하여, 사용자는 웹 UI에서 편집하고 실제 운영 환경에서는 경량화된 API JSON만 사용하여 리소스를 최적화한다 [1, 44].
- **Operation / Maintenance:** API JSON에는 모델 체크포인트의 이름이 하드코딩되므로, 서버 간 모델 공유 시 파일명 불일치 문제를 해결하기 위해 모델 해싱(SHA-256) 기술과 함께 운용한다 [45, 46].
- **Learning Path:** 먼저 GUI에서 워크플로를 완성한 후, 개발자 모드를 통해 API 포맷을 내보내고 그 구조를 분석하여 프로그래밍 방식의 제어 단계로 넘어가는 것이 표준 학습 경로이다 [14, 47].

### 인접 주변 주제 (Adjacent Topics)
- [[Node Definitions]]
  - 확장 방향: API 포맷 내 `class_type`이 참조하는 각 노드의 입력/출력 타입 정의 연구. [43]
- [[Execution Model Inversion]]
  - 확장 방향: API JSON 전체 중 필요한 노드만 선택적으로 실행하는 백엔드 최적화 원리 이해. [32, 48]

## 📝 변경 이력 (Change history)
- 2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine. 기반 소스 18개 종합 분석 완료. [1-186]