2nd/10_Wiki/Comfyui/ComfyUI API.md

---
id: comfyui-api
title: "ComfyUI API"
category: "10_Wiki/Topics"
status: "draft"
verification_status: "conceptual"
canonical_id: ""
aliases: ["API Format", "workflow_api.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 생성 방법", "automation", "API"]
raw_sources: ["NotebookLM Synthesis"]
applied_in:
  - "comfyui-workflow-to-api-converter-endpoint (bc85382)"
  - "ComfyUI-WorkflowGenerator (82df278)"
  - "ComfyUI-to-Python-Extension (6cdcc23)"
github_commit: ""
---

# [[ComfyUI API]]

## 🎯 한 줄 통찰 (One-line insight)
ComfyUI API는 노드 기반의 비주얼 워크플로를 **실행 가능한 데이터 구조(JSON)**로 직렬화하여, 창의적 프로세스를 자동화된 프로덕션 파이프라인으로 전환하는 핵심 인터페이스이다 [1, 2].

## 🧠 핵심 개념 (Core concepts)
- **API Format (workflow_api.json):** 사용자 인터페이스(UI) 메타데이터(노드 위치, 크기, 그룹 등)를 제거하고 오직 백엔드 엔진의 실행에 필요한 노드 유형과 입력 연결 정보만을 포함하는 간소화된 그래프 포맷이다 [3-5].
- **Dev Mode Options:** API 포맷으로 워크플로를 내보내기 위해 반드시 활성화해야 하는 설정으로, 활성화 시 'Save (API format)' 버튼이 노출된다 [6-8].
- **Serialization & Mapping:** 노드망을 JSON 형식의 딕셔너리로 변환하며, 각 노드는 고유한 numeric ID(예: "37")를 키로 사용하여 `class_type`과 `inputs` 값을 정의한다 [9-11].
- **Prompt Endpoint (/prompt):** 생성된 API JSON 페이로드를 ComfyUI 서버의 `/prompt` 엔드포인트로 POST 요청을 보내 실제 실행을 트리거한다 [10, 12].

## 🧩 추출된 패턴 (Extracted patterns)
- **Execution Model Inversion:** 엔진이 모든 노드를 실행하는 대신 'Save Image'와 같은 출력 노드에서 역방향으로 탐색하여 최종 결과에 필요한 의존성 노드만 식별하고 실행한다 [13].
- **Bifurcation of Formats:** 시각적 편집을 위한 Frontend 포맷(`workflow.json`)과 프로그래밍적 실행을 위한 Backend 포맷(`workflow_api.json`)을 분리하여 운영 효율성을 극대화한다 [3, 14].
- **Metadata Recovery:** PNG 파일의 `tEXt` 또는 `zTXt` 청크에 숨겨진 워크플로 JSON 데이터를 `exiftool`이나 전용 추출기를 통해 복구하여 공유 및 재사용하는 패턴이 발견된다 [15-17].

## 📖 세부 내용 (Details)

### 1. API JSON 생성 및 구조적 특징
API 포맷 JSON은 백엔드 실행 최적화를 위해 설계되었다.
- **데이터 구조:** 루트 키는 노드 ID(문자열)이며, 각 값은 `class_type`과 `inputs` 딕셔너리를 포함한다 [10, 18].
- **연결 표현:** 노드 간의 링크는 별도의 배열이 아닌 노드 입력 내에서 `[origin_node_id, output_slot_index]` 형태의 참조로 직접 임베딩된다 [3, 19].
- **위젯 값 전환:** GUI에서 사용자가 입력한 위젯 값(시드, 텍스트 등)은 API JSON의 `inputs` 필드로 직접 매핑되어 고정된 값이 된다 [19].

### 2. 프로그래밍적 조작 및 자동화
개발자는 템플릿화된 API JSON을 Python 등을 통해 동적으로 수정하여 대량 생성을 자동화할 수 있다.
- **입력값 교체:** `json` 라이브러리를 사용하여 특정 노드 ID의 `inputs` 필드(예: 프롬프트 텍스트, 시드 값)를 런타임에 변경한다 [10, 20].
- **이미지 주입:** 외부 이미지를 API로 전달할 때는 `Load Image (Base64)` 노드를 사용하거나 이미지를 서버의 `input` 디렉토리에 업로드한 후 파일명으로 참조한다 [21, 22].
- **결과 수신:** 생성 진행 상황과 결과 이미지는 WebSocket 통신을 통해 실시간으로 모니터링하며, `SaveImageWebsocket` 노드를 사용하여 바이너리 데이터를 직접 수신할 수 있다 [22].

### 3. 고도화된 생성 도구
- **ComfyUI-to-Python-Extension:** JSON 워크플로를 독립적으로 실행 가능한 `.py` 스크립트로 변환하여 서버 없이도 헤드리스 환경에서 실행 가능하게 한다 [23, 24].
- **Comfy API Simplified:** 노드 ID 대신 사용자가 지정한 노드 제목(title)으로 파라미터를 설정할 수 있게 하여 워크플로 수정 시 코드의 파손을 방지한다 [23, 25].
- **LLM 기반 생성:** 자연어 설명을 입력하면 Qwen2.5와 같은 모델이 이를 해석하여 유효한 노드 그래프 구조를 자동으로 생성하고 빌드한다 [26, 27].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **하위 호환성 문제:** ComfyUI의 빈번한 업데이트로 인해 구버전 JSON 파일이 최신 버전에서 정상적으로 작동하지 않을 수 있다는 경고가 존재한다 [28].
- **포맷의 비가역성:** API 포맷 JSON은 실행 효율은 높으나, 이를 다시 GUI로 드래그하여 로드할 경우 시각적 레이아웃(노드 위치 등)이 유실된 '스켈레톤' 상태로 나타나 편집이 어렵다 [12, 29].

## 🛠️ 적용 사례 (Applied in summary)
- **comfyui-workflow-to-api-converter-endpoint:** 클라이언트 사이드의 JS 로직을 Python으로 변환하여 서버 측에서 일반 JSON을 API JSON으로 즉시 변환하는 엔드포인트를 구현함 (커밋: bc85382) [12, 30].
- **ComfyUI-WorkflowGenerator:** 자연어 프롬프트를 기반으로 3단계 파이프라인(생성-검증-빌드)을 거쳐 실행 가능한 워크플로를 생성하는 시스템 (커밋: 82df278) [27, 31].
- **ComfyUI-to-Python-Extension:** 워크플로를 Python 코드로 번역하여 자동화 및 반복 생성에 최적화된 스크립트를 제공함 (커밋: 6cdcc23) [24, 32].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (다수의 GitHub 프로젝트를 통해 실용성 입증됨)
- **출처 신뢰도:** B (공식 문서 및 오픈소스 프로젝트 README 기반)
- **중복 검사 결과:** 신규 생성


## 🔗 관련 문서 링크 (Related document links)

### 상위/유사 개념
#### [아키텍처/기반 기술]
- [[Workflow JSON]]
  - 연결 이유: API 데이터의 근간이 되는 스키마 규격
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: 노드 속성 및 링크 스키마 v1.0의 기술적 제약 사항 [33].

#### [구현/활용 도구]
- [[API Format]]
  - 연결 이유: ComfyUI 서버 통신을 위한 필수 데이터 포맷
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: UI 메타데이터 제거 및 실행 최적화 로직 [5].
- [[ComfyUI-Manager]]
  - 연결 이유: API 실행 시 누락된 커스텀 노드 의존성 해결 도구
  - 이 개념을 통해 더 깊게 이해할 수 있는 부분: JSON 내 `class_type`을 기반으로 한 자동 노드 설치 프로세스 [34].

### 심층 후속 질문 (Deeper Research Questions)
- API JSON의 `inputs` 필드에서 노드 참조 시 사용되는 슬롯 인덱스의 정확한 매핑 규칙은 무엇인가? [35]
- `Execution Model Inversion`이 대규모 워크플로에서 실제 성능(VRAM/연산)에 미치는 정량적 영향은 어느 정도인가? [13]
- LLM 기반 워크플로 생성 시 `NodeValidator`가 사용하는 시맨틱 임베딩 방식은 커스텀 노드의 정확도를 어떻게 보장하는가? [36, 37]
- PNG 메타데이터가 손상된 경우, `exiftool` 외에 바이너리 수준에서 워크플로를 복구할 수 있는 대안적 방법이 있는가? [17, 38]
- `comfyui-workflow-to-api-converter`가 처리하는 1MB 요청 제한의 기술적 근거와 대규모 워크플로(Flux 등) 대응 방안은 무엇인가? [39, 40]

### 실무 적용 맥락 (Practical Application Contexts)
- **Implementation:** `/prompt` 엔드포인트에 전송할 JSON 페이로드를 생성하기 위해 GUI의 'Dev mode'를 활용하여 템플릿을 확보한다 [8].
- **System Design:** 프로덕션 환경에서는 사용자의 입력을 수신하는 미들웨어를 구축하고, 템플릿 JSON의 특정 노드 ID 값을 동적으로 치환하여 ComfyUI 인스턴스에 전달한다 [22, 41].
- **Operation / Maintenance:** 워크플로 변경 시 노드 ID가 변할 수 있으므로, 유지보수성을 위해 `comfy_api_simplified`와 같이 노드 제목 기반으로 접근하는 래퍼 사용을 권장한다 [23, 25].
- **Learning Path:** 기본 UI 사용법 숙지 → Dev mode 활성화 및 API JSON 구조 분석 → Python `requests` 및 `websocket`을 이용한 원격 제어 순으로 학습한다 [42, 43].

### 인접 주변 주제 (Adjacent Topics)
- [[Comfy GPT]]
  - 확장 방향: AI 에이전트가 직접 노드를 조립하고 디버깅하는 자가 최적화 시스템 연구 [27, 44].
- [[Model Hashing]]
  - 확장 방향: 파일명 대신 해시값을 사용하여 API 호출 시 모델 불일치 문제를 해결하는 기술 [45].

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