---
id: workflow-json---comfyui
title: "Workflow JSON - ComfyUI"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["ComfyUI 워크플로우 JSON", "workflow_api.json", "workflow.json"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.85
created_at: 2026-05-20
updated_at: 2026-05-20
review_reason: ""
merge_history: []
tags: ["research", "Comfyui workflow json 생성 방법"]
raw_sources: ["NotebookLM Synthesis"]
applied_in: ["comfyui-workflow-to-api-converter-endpoint/README.md", "pydn/ComfyUI-to-Python-Extension", "DanielPFlorian/ComfyUI-WorkflowGenerator", "deimos-deimos/comfy_api_simplified"]
github_commit: "bc85382"
---

# [[Workflow JSON - ComfyUI]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI Workflow JSON은 복잡한 노드 기반 생성 프로세스를 유향 비순환 그래프(DAG) 형태로 직렬화한 청사진으로, 시각적 편집을 위한 **프론트엔드 포맷**과 무두(Headless) 실행 및 자동화를 위한 **API 포맷**으로 이원화되어 관리된다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **프론트엔드 포맷 (workflow.json):** 시각적 편집과 사용자 상호작용을 위해 설계된 포맷으로, 노드의 좌표(`pos`), 크기(`size`), 그룹 구조 및 색상과 같은 UI 메타데이터를 모두 포함한다 [2-4].
- **API 포맷 (workflow_api.json):** 백엔드 실행 엔진 최적화를 위해 UI 관련 메타데이터를 제거한 스트림라인드 포맷으로, 노드 입력부 내에 연결 정보가 직접 삽입되는 구조를 가진다 [2, 5, 6].
- **메타데이터 임베딩 (Metadata Embedding):** 생성된 PNG/WebP 파일의 `tEXt` 또는 `zTXt` 청크에 JSON 데이터를 주입하여 이미지 자체가 실행 로직을 포함하는 컨테이너 역할을 수행하게 한다 [7, 8].
- **JSON 스키마 v1.0:** 유효한 워크플로우를 보장하기 위한 기술적 제약 조건으로, 고유 ID, 클래스 타입, 위젯 값 등의 속성을 정의한다 [9-11].

## 🧩 추출된 패턴 (Extracted patterns)
- **이원화 저장 패턴:** 사용자는 UI에서 수정한 내용을 `Save`로 저장(프론트엔드)하고, 외부 연동을 위해 `Dev Mode`를 활성화하여 `Save (API Format)`으로 내보낸다 [12-15].
- **역방향 그래프 탐색 (Execution Model Inversion):** 백엔드 엔진이 출력 노드(Save Image 등)로부터 역방향으로 의존성을 추적하여 실제 실행에 필요한 노드만 식별하고 나머지는 무시하는 최적화 패턴을 사용한다 [16].
- **입력값 교체 패턴 (Prompt Injection):** Python 등 프로그래밍 환경에서 템플릿 JSON을 로드한 후, 특정 노드 ID의 `inputs` 딕셔너리를 직접 수정하여 시드(seed)나 프롬프트를 동적으로 변경한다 [17-19].

## 📖 세부 내용 (Details)
### 1. 생성 및 추출 방법론
- **GUI 기반 생성:** 기본 인터페이스의 컨트롤 패널에서 `Ctrl + S`를 통해 프론트엔드 JSON을 저장할 수 있다 [12]. API 포맷을 생성하려면 설정 메뉴에서 'Enable Dev mode Options'를 활성화해야 한다 [13, 14, 20].
- **이미지 메타데이터 추출:** ComfyUI에서 생성된 이미지를 캔버스에 드래그 앤 드롭하거나 [21-23], `ExifTool`을 사용하여 `exiftool -b -workflow input.png > workflow.json` 명령어로 바이너리 데이터를 추출할 수 있다 [24, 25].
- **자동화 도구:** `comfyui-workflow-to-api-converter-endpoint`와 같은 커스텀 노드는 서버 측에서 프론트엔드 형식을 API 형식으로 실시간 변환하는 엔드포인트를 제공한다 [26-28].

### 2. 프로그래밍적 제어 및 변환
- **Python 통합:** 워크플로우 JSON은 중첩된 딕셔너리 구조이므로 Python의 `json` 라이브러리로 쉽게 조작 가능하다 [17]. `ComfyUI-to-Python-Extension`은 JSON을 아예 독립적인 실행 파일(.py)로 변환해주기도 한다 [29-31].
- **LLM 기반 생성:** `ComfyUI-WorkflowGenerator`는 자연어 설명을 입력받아 LLM(Qwen2.5 등)이 논리 구조를 합성하고, 유효성 검사(Validator)를 거쳐 최종 JSON을 빌드하는 3단계 파이프라인을 사용한다 [32-35].

### 3. 데이터 구조 분석 (v1.0 기준)
- **노드 객체 속성:** 각 노드는 고유 `id`, 노드 클래스 매핑을 위한 `type`, 실행 순서를 결정하는 `order`, 그리고 사용자 입력값인 `widgets_values`를 보유한다 [4, 9].
- **연결 구조:** 프론트엔드에서는 별도의 `links` 배열을 통해 연결을 정의하지만, API 포맷에서는 노드의 `inputs` 내부에 `[origin_id, output_slot_index]` 형태의 참조를 직접 기록한다 [2, 3, 36, 37].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **버전 호환성:** ComfyUI가 빈번하게 업데이트됨에 따라 구버전 JSON 파일이 최신 UI에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [38].
- **메타데이터 손실:** 소셜 미디어 플랫폼이나 이미지 압축 소프트웨어는 종종 이미지 내의 JSON 메타데이터 청크를 삭제하여 워크플로우 정보를 소실시킨다 [8, 38].
- **API 포맷의 비가역성:** API 포맷으로 내보낸 JSON을 다시 UI로 불러올 경우 시각적 레이아웃 정보(좌표, 그룹 등)가 유실되어 편집이 매우 어려워진다 [26, 39].

## 🛠️ 적용 사례 (Applied in summary)
- **comfyui-workflow-to-api-converter-endpoint (SethRobinson):** `/workflow/convert` 엔드포인트를 통해 비 API 워크플로우를 API 포맷으로 서버사이드 변환 수행. **commit `bc85382`**에서 콤보 위젯 대소문자 정규화 로직 적용 [40-42].
- **ComfyUI-WorkflowGenerator (DanielPFlorian):** LLM을 활용하여 자연어 지시문을 워크플로우 JSON으로 변환하는 파이프라인 구현. **commit `82df278`**에서 드롭다운 중복 모델 문제 해결 [34, 43, 44].
- **ComfyUI-to-Python-Extension (pydn):** JSON 워크플로우를 실행 가능한 Python 코드로 번역. **commit `6cdcc23`**에서 설치 문제 해결 및 README 업데이트 [30, 31, 45].
- **comfy_api_simplified:** 노드 제목(title)을 기반으로 파라미터를 설정하여 숫자 ID에 의존하지 않는 안정적인 API 제어 방식 구현 [29, 46, 47].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 다수 발견으로 검증 수준 높음)
- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM)
- **중복 검사 결과:** 신규 생성 (New discovery)

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