---
id: comfyui-api-integration
title: "ComfyUI API Integration"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: []
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", "deimos-deimos/comfy_api_simplified/examples", "Mystic/pipeline.yaml", "Mystic/new_pipeline.py", "DanielPFlorian/ComfyUI-WorkflowGenerator"]
github_commit: ""
---

# [[ComfyUI API Integration]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI API Integration은 시각적 노드 그래프를 실행 최적화된 **API JSON(Backend Format)**으로 직렬화하여, 외부 애플리케이션 및 서버리스 환경에서 생성 AI 워크플로우를 프로그래밍 방식으로 자동화하고 확장하는 핵심 매개체이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **워크플로우 포맷의 이분화 (Bifurcation):** 사용자의 시각적 편집을 위한 'Frontend Format(workflow.json)'과 서버 실행을 위해 UI 메타데이터를 제거한 'API Format(workflow_api.json)'으로 구분된다 [2, 4-6].
- **API JSON 직렬화:** 노드 위치, 크기, 그룹 등 시각적 정보를 배제하고 노드 클래스(class_type), 입력 매개변수(inputs), 노드 간 연결 관계만을 포함하는 압축된 실행 그래프이다 [2, 6, 7].
- **개발자 모드 (Dev Mode):** 표준 UI에서는 숨겨져 있으며, 설정에서 활성화해야만 API 전용 JSON을 내보낼 수 있는 기능이 활성화된다 [8-12].
- **엔드포인트 연동:** 생성된 API JSON은 ComfyUI 서버의 `/prompt` 엔드포인트로 전송되어 실제 이미지나 미디어 생성 명령으로 변환된다 [2, 4, 12, 13].

## 🧩 추출된 패턴 (Extracted patterns)
- **개발자 모드 활성화 패턴:** `Settings` 아이콘 클릭 → `Enable Dev mode Options` 체크 → 메뉴의 `Save (API Format)` 버튼 사용 [8-11, 14].
- **메타데이터 추출 패턴:** PNG/WebP 이미지의 `tEXt` 또는 `zTXt` 청크에 포함된 JSON 데이터를 `exiftool`이나 전용 추출 도구를 통해 복구하여 재사용하는 방식 [15-18].
- **동적 템플릿 패턴:** 기본 JSON 파일을 로드한 후 Python 딕셔너리 조작을 통해 특정 노드 ID의 `seed`, `prompt`, `image` 등의 값을 실시간으로 변경하여 큐에 삽입하는 전략 [13, 19, 20].
- **고유 식별자(ID) 타겟팅:** 각 노드에 부여된 숫자형 문자열 키(예: "37")를 사용하여 특정 노드의 입력 필드에 접근하는 패턴 [5, 20].

## 📖 세부 내용 (Details)
ComfyUI 워크플로우 JSON은 생성 AI 프로세스를 **유향 비순환 그래프(DAG)**로 정의하며, 이를 직렬화함으로써 이식성과 자동화를 실현한다 [1].

### 1. 워크플로우 JSON의 주요 유형 및 구조
- **Frontend JSON (workflow.json):** Litegraph 표준을 따르며 노드 좌표, 그룹화, 색상 등 캔버스 레이아웃 정보를 포함한다 [2, 5, 21].
- **API JSON (workflow_api.json):** 백엔드 엔진이 프롬프트를 실행하는 데 필요한 논리적 연결만 남긴 효율적인 그래프이다 [2, 4, 6]. 링크는 별도 객체가 아닌 노드 입력 내에 직접 임베딩된다 [2, 22].
- **구조적 제약:** JSON v1.0 스키마에 따라 각 노드는 고유 `id`, `type`, `inputs`, `outputs`를 가져야 하며, 실행 엔진은 출력 노드에서 역방향으로 그래프를 탐색하여 필요한 의존성만 실행하는 '실행 모델 반전' 방식을 사용한다 [23-25].

### 2. JSON 생성 및 획득 방법
- **수동 내보내기:** 웹 인터페이스에서 개발자 모드를 활성화한 후 전용 저장 버튼을 사용한다 [8, 9, 11].
- **알고리즘 추출:** ComfyUI가 생성한 PNG 파일에는 워크플로우가 메타데이터로 자동 저장되므로, 이를 드래그 앤 드롭하거나 `exiftool` 명령어를 사용하여 추출할 수 있다 [15, 17, 26-28].
- **자연어 기반 생성:** LLM(예: Qwen2.5-14B)을 사용하여 자연어 설명을 논리적 그래프 구조로 합성하고 로컬 노드 카탈로그와 대조하여 유효한 JSON으로 변환하는 방식이 도입되었다 [29-32].

### 3. 프로그래밍 방식의 통합 및 변환
- **Python 직접 조작:** Python의 `json` 라이브러리를 사용하여 노드 ID를 기반으로 텍스트나 이미지 데이터를 업데이트한다 [19, 20]. 이미지는 주로 Base64로 인코딩되어 JSON 내에 직접 포함된다 [13, 33].
- **추상화 래퍼:** `comfy_api_simplified`와 같은 라이브러리는 숫자 ID 대신 노드 제목으로 매개변수를 설정하게 하여 유지보수성을 높인다 [34, 35].
- **스크립트 변환:** `ComfyUI-to-Python-Extension`은 JSON 워크플로우를 실행 가능한 독립형 `.py` 스크립트로 변환하여 헤드리스 환경에서 실행할 수 있게 한다 [34, 36, 37].

### 4. API 기반 자동화 및 배포
- **서버리스 플랫폼:** Replicate나 Mystic 같은 서비스는 API JSON 블롭을 입력받아 클라우드 GPU에서 실행하고 결과를 반환하는 엔드포인트를 제공한다 [9, 38-40].
- **의존성 관리:** JSON 로드 시 누락된 커스텀 노드는 '빨간 박스'로 표시되며, `ComfyUI-Manager`를 통해 자동으로 식별 및 설치할 수 있다 [41-43].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **포맷 호환성 문제:** 표준 저장 방식으로 생성된 JSON은 API 엔드포인트에서 오류를 발생시키므로 반드시 API 포맷으로의 변환이 필요하다 [12].
- **메타데이터 손실:** 소셜 미디어나 이미지 편집기(GIMP 등)를 통해 이미지를 전송 또는 수정할 경우 워크플로우 메타데이터가 삭제될 수 있다는 경고가 반복적으로 확인된다 [16, 26, 44, 45].
- **노드 ID 변동성:** 워크플로우를 UI에서 수정하면 노드 ID가 변경될 수 있어, 하드코딩된 Python 스크립트가 파손될 위험이 존재한다 [19, 34]. 이에 대한 해결책으로 노드 제목 기반 매핑이 권장된다 [34, 35].

## 🛠️ 적용 사례 (Applied in summary)
- **서버 측 변환 엔드포인트:** `comfyui-workflow-to-api-converter-endpoint`는 클라이언트 측의 자바스크립트 로직을 파이썬으로 변환하여 서버에서 일반 JSON을 API JSON으로 실시간 변환하는 `/workflow/convert` 엔드포인트를 구현했다 [12, 46, 47].
- **독립 실행형 스크립트 변환:** `pydn/ComfyUI-to-Python-Extension` 프로젝트는 `Save As Script` 기능을 통해 워크플로우를 `.py` 파일로 다운로드하여 자동화된 실행 환경을 구축했다 [37, 48].
- **매개변수 스케줄링:** `comfy_api_simplified` 라이브러리는 수백 개의 이미지를 야간에 생성하기 위해 여러 프롬프트와 매개변수를 반복 실행하는 예제 코드를 제공한다 [35, 49].
- **배너 광고 자동 생성:** ComfyUI API를 Python과 연동하여 입력 이미지와 텍스트를 변경하며 대량의 광고 소재를 생성하는 실제 사례가 보고되었다 [50].
- **Mystic 파이프라인 배포:** `pipeline.yaml`과 `new_pipeline.py`를 사용하여 텍스트-비디오 워크플로우를 서버리스 엔드포인트로 배포하는 구조가 상세히 기술되었다 [51-53].

## ✅ 검증 상태 및 신뢰도
- **상태:** 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.