2nd/10_Wiki/Topics/Comfyui/Workflow JSON (Frontend Format).md

---
id: workflow-json-(frontend-format)
title: "Workflow JSON (Frontend Format)"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["workflow.json"]
duplicate_of: ""
source_trust_level: "B"
confidence_score: 0.90
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: ["workflow.json", "SethRobinson/comfyui-workflow-to-api-converter-endpoint/bc85382"]
github_commit: "bc85382"
---

# [[Workflow JSON (Frontend Format)]]

## 🎯 한 줄 통찰 (One-line insight)
사용자 인터페이스의 시각적 레이아웃 정보와 노드 그래프의 모든 논리적 연결성을 보존하여 인간 중심의 공유와 편집을 가능케 하는 ComfyUI의 기본 직렬화 규격이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **시각적 메타데이터 보존 (Visual Metadata Persistence):** 노드의 좌표(`pos`), 크기(`size`), 그룹 구조, 색상 및 노드 접힘 상태(`flags`)와 같은 UI 전용 데이터를 포함한다 [2-5].
- **명시적 링크 표현 (Explicit Link Representation):** 노드 입력부에 연결 정보를 내장하는 대신, 별도의 `links` 배열을 통해 시작점과 끝점 슬롯을 정의하는 명시적 연결 객체 형식을 사용한다 [2, 3, 6, 7].
- **Litegraph 표준 준수 (Litegraph Standard):** 웹 기반 그래프 시각화 엔진인 Litegraph 형식을 따라 설계되어 브라우저 캔버스에서의 정확한 복원을 보장한다 [2, 7].
- **미디어 임베딩 속성 (Media Embedding):** ComfyUI에서 생성된 PNG 또는 WebP 이미지의 메타데이터(tEXt 또는 zTXt 청크)에 직접 주입되어 생성 로직을 운반하는 컨테이너 역할을 수행한다 [8-10].

## 🧩 추출된 패턴 (Extracted patterns)
- **직렬화 이원화 (Serialization Bifurcation):** ComfyUI는 시각적 편집용인 'Frontend 포맷'과 서버 실행 최적화용인 'API 포맷'으로 데이터를 분리하여 관리한다 [2].
- **중복 데이터 전략 (Redundancy Strategy):** 생성된 이미지 메타데이터 내에 시각적 복원용 `workflow.json`과 실행용 `prompt` 데이터를 동시에 저장하여 상호 보완성을 확보한다 [9].
- **역방향 그래프 탐색 (Execution Model Inversion):** 캔버스에 수많은 노드가 존재하더라도 실행 엔진은 출력 노드에서 시작해 필요한 의존성 노드만 역으로 추적하므로, Frontend JSON에 불필요한 노드가 포함되어도 실행 성능에 영향을 주지 않는다 [11].

## 📖 세부 내용 (Details)
Frontend 포맷은 주로 `workflow.json`이라는 파일명으로 사용되며, ComfyUI 웹 인터페이스에서 사용자가 수행하는 'Visual Programming'의 결과를 저장하는 소스 코드와 같은 역할을 한다 [2, 12, 13].

### 1. 주요 데이터 구조 (Schema v1.0)
- **Nodes Array:** 각 노드 객체는 고유 ID, 클래스 타입(`type`), 좌표, 크기, 위젯 값(`widgets_values`), 실행 순서(`order`), 모드(활성/바이패스 등)를 포함한다 [4, 5].
- **Links Array:** 6개의 항목으로 구성된 배열 또는 구조화된 객체로, `origin_id`, `origin_slot`, `target_id`, `target_slot`을 정의하여 노드 간의 데이터 흐름을 명시한다 [6].

### 2. 생성 및 획득 방법
- **GUI 수동 내보내기:** 제어 패널 메뉴의 'Export' 옵션 또는 단축키 `Ctrl + S`(macOS는 `Cmd + S`)를 사용하여 현재 캔버스의 상태를 JSON으로 다운로드할 수 있다 [12, 14].
- **미디어 메타데이터 추출:** 
    - **드래그 앤 드롭:** ComfyUI에서 생성된 PNG 이미지를 브라우저 캔버스에 직접 끌어다 놓으면 내장된 JSON을 통해 노드 배치가 복원된다 [14-16].
    - **CLI 도구 활용:** `exiftool -b -workflow input.png > workflow.json` 명령어를 통해 바이너리 태그에서 JSON 데이터를 분리해낼 수 있다 [17, 18].
    - **웹 도구:** Weird Wonderful AI Art의 'Workflow Extractor'와 같은 브라우저 기반 도구를 통해 온라인 이미지에서 데이터를 추출할 수 있다 [19, 20].

### 3. API 포맷과의 차별점
Frontend 포맷은 인간이 읽기 쉽고 UI를 완벽히 재구성할 수 있도록 설계되었으나, `/prompt` 엔드포인트에 직접 전달할 경우 오류가 발생할 수 있다 [21]. API 호출을 위해서는 UI 메타데이터가 제거되고 노드 간 연결이 입력 필드에 직접 참조된 'API JSON' 형식이 필요하며, 이는 설정에서 'Dev mode'를 활성화해야만 생성 가능하다 [2, 3, 13, 22].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **포맷 호환성 이슈:** ComfyUI는 업데이트가 매우 빈번하여, 구버전에서 생성된 Frontend JSON 파일이 신버전에서 올바르게 작동하지 않거나 노드가 빨간색 박스로 표시되는(Missing Custom Nodes) 현상이 발생할 수 있다 [14, 23].
- **데이터 휘발성:** 이미지 편집기(GIMP 등)로 처리하거나 소셜 미디어 플랫폼에 업로드할 경우, 파일 크기 최적화 과정에서 비표준 메타데이터인 Frontend JSON 정보가 삭제되어 워크플로우 복원이 불가능해지는 경우가 많다 [9, 24].

## 🛠️ 적용 사례 (Applied in summary)
- **SethRobinson/comfyui-workflow-to-api-converter-endpoint:** 클라이언트 측의 자바스크립트 변환 로직을 서버 측 파이썬으로 구현하여, `workflow.json`만으로 API 호출이 가능하도록 변환하는 기능을 제공한다 [21, 25].
- **ComfyUI-to-Python-Extension:** Frontend JSON 메타데이터를 포함한 파이썬 스크립트를 생성하여, 실행 후 저장된 결과물을 다시 ComfyUI UI로 드래그 앤 드롭하여 복원할 수 있도록 지원한다 [26].
- **기본 저장 규칙:** ComfyUI의 `Save Image` 노드는 실행 시 최종 이미지에 전체 노드 그래프와 설정을 주입하며, 이는 `workflow.json` 규격을 따른다 [16].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 발견 시 applied/validated로 승격 가능)
- **출처 신뢰도:** B (Official Documentation / Primary Source via NotebookLM)
- **중복 검사 결과:** 신규 생성 (New discovery)

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