---
id: api-json
title: "API JSON"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["workflow_api.json", "Backend Format", "API Format"]
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-workflow-to-api-converter-endpoint", "ComfyUI-to-Python-Extension", "comfy_api_simplified"]
github_commit: ""
---

# [[API JSON]]

## 🎯 한 줄 통찰 (One-line insight)
API JSON은 ComfyUI의 시각적 인터페이스 요소를 배제하고 순수 실행 로직만을 추상화하여 백엔드 엔진의 프로그래밍적 제어와 자동화를 가능케 하는 핵심 데이터 규격이다 [1, 2].

## 🧠 핵심 개념 (Core concepts)
1. **백엔드 실행 그래프 (Backend Execution Graph):** 노드 위치, 크기, 그룹 등 UI 관련 메타데이터를 제거하고 실행에 필요한 노드 타입과 입력값, 연결 관계만을 남긴 콤팩트한 형식이다 [1, 3].
2. **임베딩된 참조 구조 (Reference-based Linking):** 별도의 링크 배열을 사용하는 프론트엔드 형식과 달리, 노드 입력 필드 내에 직접 소스 노드 ID와 출력 슬롯 인덱스를 배열 형태로 기술한다 [1, 3, 4].
3. **개발자 모드 (Dev Mode) 활성화:** 표준 ComfyUI 환경에서 API JSON을 추출하기 위해 설정(Settings) 메뉴에서 반드시 선행 활성화해야 하는 옵션이다 [5-7].
4. **프로그래밍적 엔드포인트 호환성:** `/prompt` 엔드포인트에 페이로드로 직접 전달되어 서버 측에서 즉시 실행될 수 있도록 최적화된 구조를 가진다 [8-10].

## 🧩 추출된 패턴 (Extracted patterns)
- **Bifurcation (이원화) 저장 패턴:** 사용자의 시각적 편집을 위한 `workflow.json`과 기계적 실행을 위한 `workflow_api.json`을 분리하여 각 용도에 최적화된 성능과 관리 편의성을 제공한다 [1, 8, 11].
- **Metadata Chunk 중복 저장:** 생성된 PNG 파일의 tEXt 또는 zTXt 청크에 프론트엔드 워크플로우와 API 프롬프트를 모두 저장하여, 이미지 하나로 시각적 복원과 API 실행을 동시에 보장한다 [12, 13].
- **Execution Model Inversion:** 엔진이 출력 노드에서부터 역방향으로 그래프를 탐색하여 결과 생성에 필요한 노드만 선별 실행함으로써 데이터 처리 효율을 극대화한다 [14].

## 📖 세부 내용 (Details)
### 1. 기술적 구조 및 사양
API JSON은 루트 키가 **노드 ID(문자열)**로 구성된 단일 JSON 객체 구조를 취한다 [15, 16]. 각 노드 객체는 클래스 이름인 `class_type`과 사용자 입력 및 연결 정보를 포함하는 `inputs` 딕셔너리로 이루어진다 [3, 17]. 노드 간의 연결은 `inputs` 내에 `[노드_ID, 출력_슬롯_인덱스]` 형식의 배열로 표현되어 그래프 구조를 형성한다 [4, 18]. 이는 Litegraph 표준을 따르는 프론트엔드 포맷보다 훨씬 파일 크기가 작고 처리가 빠르다 [8].

### 2. 수동 생성 및 추출 방법
가장 기본적인 생성 방법은 ComfyUI 웹 인터페이스를 이용하는 것이다. 설정 메뉴에서 **"Enable Dev mode Options"**를 체크하면 컨트롤 패널에 **"Save (API Format)"** 버튼이 노출되며, 이를 통해 즉시 다운로드 가능하다 [5, 6, 19, 20]. 또한, 이미 생성된 PNG 이미지에서 `exiftool`과 같은 CLI 도구를 사용해 메타데이터에 숨겨진 API JSON(Prompt) 데이터를 추출할 수도 있다 [21, 22].

### 3. 자동화 및 프로그래밍적 생성
- **LLM 기반 생성:** `ComfyUI-WorkflowGenerator`는 자연어 지시를 해석하여 논리적 합성, 의미론적 검증, 그래프 컴파일 단계를 거쳐 실행 가능한 API JSON을 자동으로 구축한다 [23-25].
- **동적 변환:** `comfyui-workflow-to-api-converter-endpoint` 커스텀 노드는 서버측에서 `/workflow/convert` 엔드포인트를 제공하여, 시각적 정보가 포함된 표준 JSON을 실시간으로 API 포맷으로 변환해준다 [10, 26, 27].
- **Python 래퍼 및 확장:** `comfy_api_simplified`나 `ComfyUI-to-Python-Extension`은 API JSON을 로드하여 특정 노드의 파라미터(시드, 프롬프트 등)를 동적으로 수정한 후 큐잉하거나, 전체 워크플로우를 독립 실행형 Python 스크립트로 변환하는 기능을 제공한다 [28-30].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **버전 호환성 제한:** ComfyUI는 업데이트가 매우 잦아 이전 버전에서 생성된 API JSON이 최신 버전의 노드 레지스트리나 스키마와 충돌하여 작동하지 않을 가능성이 상존한다 [31].
- **데이터 파괴 위험:** 표준 이미지 편집기나 소셜 미디어 플랫폼을 통해 이미지를 공유할 경우, API JSON이 포함된 메타데이터 청크가 자동으로 삭제되어 워크플로우 정보가 영구 손실될 수 있다 [12, 31].

## 🛠️ 적용 사례 (Applied in summary)
- **Mystic Python SDK 연동:** `workflow_api.json`을 사용하여 텍스트-투-비디오 워크플로우를 서버리스 엔드포인트로 배포하며, Python 스크립트에서 입력 프롬프트를 동적으로 주입한다 [32, 33].
- **Replicate API 호출:** `fofr/any-comfyui-workflow` 모델을 통해 API JSON을 직접 입력받아 원격 GPU에서 워크플로우를 실행한다 [7, 34].
- **ComfyUI-to-Python-Extension:** CLI를 통해 `workflow_api.json`을 입력 파일로 받아 실행 가능한 `.py` 스크립트를 생성하며, 이때 `--input_file` 플래그로 API JSON 경로를 지정한다 [35, 36].
- **Lou@blog Python 코드:** `urllib`와 `websocket`을 사용하여 API JSON의 특정 노드 ID(예: #37 TextInput)의 `inputs.text` 값을 교체한 후 서버에 요청을 보내는 구조를 구현하였다 [16, 37].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨에 따라 추후 applied/validated 승격 가능)
- **출처 신뢰도:** B (공식 문서 및 실제 오픈소스 프로젝트의 README/구현 코드를 바탕으로 함)
- **중복 검사 결과:** 신규 생성 (New discovery)

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