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

# [[workflow_api.json]]

## 🎯 한 줄 통찰 (One-line insight)
`workflow_api.json`은 UI 메타데이터를 제거하고 노드 간의 기능적 연결성만을 추출하여 ComfyUI 백엔드 엔진이 즉시 실행할 수 있도록 최적화된 직렬화된 실행 그래프이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **백엔드/API 포맷 (Backend/API Format):** 시각적 요소(위치, 크기, 그룹 등)를 배제하고 서버 사이드 처리 및 프로그램 기반 자동화에 최적화된 포맷이다 [1, 3].
- **평탄화된 그래프 (Flattened Execution Graph):** 링크가 별도의 연결 객체가 아닌 노드 입력 내부에 직접 참조(Origin Node ID 및 Output Slot) 형태로 포함된 구조이다 [1, 3, 4].
- **개발자 모드 종속성 (Dev Mode Dependency):** 표준 내보내기 기능과 달리, 설정 메뉴에서 'Dev mode Options'를 활성화해야만 생성이 가능한 특수 포맷이다 [5-7].
- **/prompt 엔드포인트 호환성:** ComfyUI 서버의 API 엔드포인트에 직접 전달하여 워크플로우를 실행하기 위한 표준 데이터 구조로 사용된다 [2, 8, 9].

## 🧩 추출된 패턴 (Extracted patterns)
- **포맷 분화 (Schema Bifurcation):** 사용자 상호작용을 위한 'Frontend JSON(workflow.json)'과 실행을 위한 'API JSON(workflow_api.json)'을 철저히 분리하여 운영 효율성을 극대화한다 [1, 2, 10].
- **노드 식별 기반 접근:** 각 노드는 고유한 숫자형 키(String ID)로 식별되며, 이를 통해 외부 스크립트에서 특정 노드의 입력을 동적으로 수정할 수 있다 [11, 12].
- **역방향 의존성 탐색 (Execution Model Inversion):** 엔진이 출력 노드(Save Image 등)로부터 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 실행하는 구조를 지원한다 [13].

## 📖 세부 내용 (Details)
**데이터 구조 및 속성**  
`workflow_api.json`은 루트 레벨의 키가 노드 ID(문자열)인 단일 JSON 객체 구조를 가진다 [14]. 각 노드 정의에는 `class_type`(노드 클래스 이름)과 `inputs`(위젯 값 및 타 노드 출력에 대한 연결 정보)가 포함되며, 선택적으로 `_meta` 필드가 존재할 수 있다 [11, 14]. 링크 표현 방식은 `[node_id, output_slot_index]` 형태의 배열로 입력 필드에 직접 삽입된다 [3, 15].

**생성 및 추출 프로세스**  
1. **GUI 내보내기:** 설정 메뉴의 톱니바퀴 아이콘을 통해 'Enable Dev mode Options'를 활성화한 후, 제어판에 나타나는 'Save (API Format)' 또는 'Export (API)' 버튼을 사용하여 생성한다 [6, 7, 14, 16].
2. **이미지 메타데이터 추출:** ComfyUI에서 생성된 PNG 파일의 `tEXt` 또는 `zTXt` 청크에는 워크플로우(Frontend)와 프롬프트(API) 데이터가 함께 저장되며, `exiftool`이나 전문 추출 도구를 통해 이를 복구할 수 있다 [17-20].
3. **서버 사이드 변환:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드를 사용하면 일반 워크플로우 포맷을 실시간으로 API 포맷으로 변환하는 엔드포인트를 구축할 수 있다 [9, 21].

**프로그래밍적 활용**  
이 포맷은 Python의 `json` 라이브러리를 통해 딕셔너리 형태로 로드되어 씨드(seed), 프롬프트 텍스트, 노이즈 강도 등의 파라미터를 동적으로 변경하는 데 사용된다 [11, 22]. `Replicate`, `Mystic`, `RunComfy` 등 클라우드 API 서비스는 이 포맷을 기반으로 워크플로우를 서버리스 함수나 컨테이너화된 서비스로 배포한다 [3, 23, 24].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **정보 손실의 비가역성:** API 포맷을 다시 ComfyUI 캔버스로 불러올 경우, UI 메타데이터가 삭제되어 있기 때문에 노드들이 겹쳐 보이거나 그룹 정보가 사라진 '뼈대(skeleton)' 상태로 복원되는 한계가 있다 [9, 25].
- **버전 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있으며, 특히 커스텀 노드의 클래스 타입 변경에 취약하다 [26, 27].

## 🛠️ 적용 사례 (Applied in summary)
- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 변환 로직을 파이썬으로 구현하여 `/workflow/convert` 엔드포인트를 제공함 [9, 28]. (Git Commit: `bc85382`)
- **ComfyUI-to-Python-Extension:** `workflow_api.json` 입력을 받아 실행 가능한 `.py` 스크립트로 변환하는 기능을 지원함 [29, 30].
- **Mystic Pipeline Deployment:** `new_pipeline.py` 스크립트 내에서 API 포맷 JSON을 로드하여 입력 프롬프트를 주입하고 실행하는 템플릿 구조에 적용됨 [31, 32].
- **Replicate fofr/any-comfyui-workflow:** API JSON 블롭을 입력받아 이미지/비디오를 생성하는 범용 워크플로우 모델의 핵심 입력 데이터로 활용됨 [23, 33].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 다수 발견으로 검증 가능)
- **출처 신뢰도:** B (공식 문서 및 개발자 가이드 기반 합성)
- **중복 검사 결과:** 신규 생성 (New discovery)

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