2nd/10_Wiki/Topics/Comfyui/-prompt endpoint.md

---
id: /prompt-endpoint
title: "/prompt endpoint"
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: ["comfy_api_python.py", "/workflow/convert", "new_pipeline.py", "comfyui_to_python.py"]
github_commit: ""
---

# [[/prompt endpoint]]

## 🎯 한 줄 통찰 (One-line insight)
`/prompt endpoint`는 시각적 노드 그래프를 실행 가능한 백엔드 명령으로 전환하여 ComfyUI의 강력한 생성 능력을 외부 애플리케이션 및 자동화 파이프라인과 연결하는 핵심 게이트웨이이다 [1-3].

## 🧠 핵심 개념 (Core concepts)
- **API Format (Backend Format):** `/prompt` 엔드포인트는 시각적 메타데이터가 제거되고 실행에 필수적인 노드 입력 및 연결 정보만 포함된 전용 JSON 형식을 요구한다 [1, 4, 5].
- **Flattened Execution Graph:** 엔드포인트에 전달되는 데이터는 링크가 노드 입력 내부에 직접 삽입된 형태로, 백엔드 엔진이 즉시 처리할 수 있도록 최적화된 구조를 가진다 [1, 6, 7].
- **Programmatic Interaction:** HTTP POST 요청을 통해 JSON 페이로드를 전송함으로써 GUI 없이도 워크플로우를 실행하고 실시간으로 파라미터를 수정할 수 있다 [8-10].
- **Self-Contained Requests:** 이미지 입력을 Base64로 인코딩하여 JSON 내에 직접 포함시킴으로써 별도의 파일 저장 없이도 서버 사이드 처리가 가능한 독립적인 생성 요청을 구성한다 [10, 11].

## 🧩 추출된 패턴 (Extracted patterns)
- **UI-API 분리 패턴:** 사용자 인터페이스를 위한 `workflow.json`(Frontend)과 실제 실행을 위한 `workflow_api.json`(Backend)을 엄격히 구분하여 효율성을 극대화한다 [4, 12, 13].
- **직접 딕셔너리 조작(Direct Dictionary Manipulation):** Python 등의 언어로 JSON 파일을 로드한 후, 노드 ID를 키로 사용하여 프롬프트나 시드(Seed) 값을 동적으로 교체하는 패턴이 주로 사용된다 [9, 10].
- **웹소켓(WebSocket) 결합 구조:** `/prompt` 엔드포인트로 작업을 큐잉(Queueing)한 후, `/ws` 엔드포인트를 통해 진행 상황과 최종 생성된 바이너리 데이터를 실시간으로 수신한다 [10].
- **실행 모델 인버전(Execution Model Inversion):** 백엔드 엔진은 전달된 JSON에서 최종 출력 노드(Save Image 등)부터 역추적하여 필요한 노드만 실행하는 최적화 로직을 수행한다 [14].

## 📖 세부 내용 (Details)
`/prompt endpoint`는 ComfyUI 서버가 외부로부터 실행 명령을 받는 표준 HTTP API 경로이다 [3, 10]. 이 엔드포인트는 일반적인 저장용 JSON(Frontend Format)과 호환되지 않으며, 반드시 **'Dev mode Options'**를 활성화하여 추출한 **API Format JSON**을 페이로드로 사용해야 한다 [8, 15, 16].

API 요청 시 JSON의 루트 키는 노드 ID(숫자 또는 문자열)가 되며, 각 값은 해당 노드의 `class_type`과 `inputs`를 포함하는 객체로 구성된다 [9, 17]. 이때 입력 필드는 단순한 값뿐만 아니라 다른 노드의 출력 슬롯에 대한 참조(`[node_id, slot_index]`)를 포함하여 데이터 흐름을 정의한다 [6].

서버는 요청을 받으면 내부적으로 `validate_prompt` 함수를 호출하여 그래프의 무결성을 검증한 후, 이를 `ExecutionList`로 변환하여 순차적으로 노드를 실행한다 [18]. 만약 워크플로우에 필요한 커스텀 노드가 로컬 서버에 설치되어 있지 않으면 실행이 거부되므로, ComfyUI Manager 등을 통한 사전 의존성 해결이 필수적이다 [19-21].

## ⚖️ 모순 및 업데이트 (Contradictions & updates)
- **호환성 문제:** 일반적인 `Save` 버튼으로 생성된 JSON을 `/prompt` 엔드포인트에 직접 전송하면 에러가 발생한다 [16]. 반드시 `Save (API Format)`를 사용하거나 별도의 변환 도구를 거쳐야 한다 [15, 16].
- **메타데이터 손실:** API 형식으로 변환된 JSON은 노드 위치나 그룹 정보가 모두 삭제되므로, 이를 다시 ComfyUI 캔버스에 드래그하면 시각적 레이아웃이 파괴된 "뼈대" 형태만 남게 된다 [22]. 따라서 원본 워크플로우 파일의 별도 보관이 권장된다 [22].

## 🛠️ 적용 사례 (Applied in summary)
- **comfy_api_python.py:** Python의 `urllib.request`를 사용하여 `http://{server_address}/prompt` 경로에 JSON 데이터를 POST 방식으로 전송하는 실제 구현 코드가 포함되어 있음 [10].
- **/workflow/convert 엔드포인트:** 시각적 워크플로우 JSON을 서버 사이드에서 즉시 API 형식으로 변환하여 `/prompt` 엔드포인트에 바로 보낼 수 있도록 지원하는 커스텀 노드가 개발됨 [16, 21].
- **Mystic Pipeline (new_pipeline.py):** 클라우드 환경에서 ComfyUI 서버를 구동하고 사용자 입력을 워크플로우 JSON에 주입하여 실행하는 파이프라인 자동화에 적용됨 [23, 24].
- **ComfyUI-to-Python-Extension:** API 포맷의 워크플로우 JSON을 독립적으로 실행 가능한 `.py` 스크립트로 변환하는 CLI 도구 및 라이브러리 구조에서 핵심 참조 대상으로 사용됨 [25, 26].

## ✅ 검증 상태 및 신뢰도
- **상태:** draft
- **검증 단계:** conceptual (실제 적용 사례 다수 발견됨)
- **출처 신뢰도:** B (Official Documentation / API Docs / GitHub Source Code)
- **중복 검사 결과:** 신규 생성 (New discovery)

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