API JSON은 ComfyUI의 시각적 인터페이스 요소를 배제하고 순수 실행 로직만을 추상화하여 백엔드 엔진의 프로그래밍적 제어와 자동화를 가능케 하는 핵심 데이터 규격이다 [1, 2].
🧠 핵심 개념 (Core concepts)
백엔드 실행 그래프 (Backend Execution Graph): 노드 위치, 크기, 그룹 등 UI 관련 메타데이터를 제거하고 실행에 필요한 노드 타입과 입력값, 연결 관계만을 남긴 콤팩트한 형식이다 [1, 3].
임베딩된 참조 구조 (Reference-based Linking): 별도의 링크 배열을 사용하는 프론트엔드 형식과 달리, 노드 입력 필드 내에 직접 소스 노드 ID와 출력 슬롯 인덱스를 배열 형태로 기술한다 [1, 3, 4].
개발자 모드 (Dev Mode) 활성화: 표준 ComfyUI 환경에서 API JSON을 추출하기 위해 설정(Settings) 메뉴에서 반드시 선행 활성화해야 하는 옵션이다 [5-7].
프로그래밍적 엔드포인트 호환성:/prompt 엔드포인트에 페이로드로 직접 전달되어 서버 측에서 즉시 실행될 수 있도록 최적화된 구조를 가진다 [8-10].
🧩 추출된 패턴 (Extracted patterns)
Bifurcation (이원화) 저장 패턴: 사용자의 시각적 편집을 위한 workflow.json과 기계적 실행을 위한 workflow_api.json을 분리하여 각 용도에 최적화된 성능과 관리 편의성을 제공한다 [1, 8, 11].
Metadata Chunk 중복 저장: 생성된 PNG 파일의 tEXt 또는 zTXt 청크에 프론트엔드 워크플로우와 API 프롬프트를 모두 저장하여, 이미지 하나로 시각적 복원과 API 실행을 동시에 보장한다 [12, 13].
Execution Model Inversion: 엔진이 출력 노드에서부터 역방향으로 그래프를 탐색하여 결과 생성에 필요한 노드만 선별 실행함으로써 데이터 처리 효율을 극대화한다 [14].
📖 세부 내용 (Details)
1. 기술적 구조 및 사양
API JSON은 루트 키가 **노드 ID(문자열)**로 구성된 단일 JSON 객체 구조를 취한다 [15, 16]. 각 노드 객체는 클래스 이름인 class_type과 사용자 입력 및 연결 정보를 포함하는 inputs 딕셔너리로 이루어진다 [3, 17]. 노드 간의 연결은 inputs 내에 [노드_ID, 출력_슬롯_인덱스] 형식의 배열로 표현되어 그래프 구조를 형성한다 [4, 18]. 이는 Litegraph 표준을 따르는 프론트엔드 포맷보다 훨씬 파일 크기가 작고 처리가 빠르다 [8].
2. 수동 생성 및 추출 방법
가장 기본적인 생성 방법은 ComfyUI 웹 인터페이스를 이용하는 것이다. 설정 메뉴에서 **"Enable Dev mode Options"**를 체크하면 컨트롤 패널에 "Save (API Format)" 버튼이 노출되며, 이를 통해 즉시 다운로드 가능하다 [5, 6, 19, 20]. 또한, 이미 생성된 PNG 이미지에서 exiftool과 같은 CLI 도구를 사용해 메타데이터에 숨겨진 API JSON(Prompt) 데이터를 추출할 수도 있다 [21, 22].
3. 자동화 및 프로그래밍적 생성
LLM 기반 생성:ComfyUI-WorkflowGenerator는 자연어 지시를 해석하여 논리적 합성, 의미론적 검증, 그래프 컴파일 단계를 거쳐 실행 가능한 API JSON을 자동으로 구축한다 [23-25].
동적 변환:comfyui-workflow-to-api-converter-endpoint 커스텀 노드는 서버측에서 /workflow/convert 엔드포인트를 제공하여, 시각적 정보가 포함된 표준 JSON을 실시간으로 API 포맷으로 변환해준다 [10, 26, 27].
Python 래퍼 및 확장:comfy_api_simplified나 ComfyUI-to-Python-Extension은 API JSON을 로드하여 특정 노드의 파라미터(시드, 프롬프트 등)를 동적으로 수정한 후 큐잉하거나, 전체 워크플로우를 독립 실행형 Python 스크립트로 변환하는 기능을 제공한다 [28-30].
⚖️ 모순 및 업데이트 (Contradictions & updates)
버전 호환성 제한: ComfyUI는 업데이트가 매우 잦아 이전 버전에서 생성된 API JSON이 최신 버전의 노드 레지스트리나 스키마와 충돌하여 작동하지 않을 가능성이 상존한다 [31].
데이터 파괴 위험: 표준 이미지 편집기나 소셜 미디어 플랫폼을 통해 이미지를 공유할 경우, API JSON이 포함된 메타데이터 청크가 자동으로 삭제되어 워크플로우 정보가 영구 손실될 수 있다 [12, 31].
🛠️ 적용 사례 (Applied in summary)
Mystic Python SDK 연동:workflow_api.json을 사용하여 텍스트-투-비디오 워크플로우를 서버리스 엔드포인트로 배포하며, Python 스크립트에서 입력 프롬프트를 동적으로 주입한다 [32, 33].
Replicate API 호출:fofr/any-comfyui-workflow 모델을 통해 API JSON을 직접 입력받아 원격 GPU에서 워크플로우를 실행한다 [7, 34].
ComfyUI-to-Python-Extension: CLI를 통해 workflow_api.json을 입력 파일로 받아 실행 가능한 .py 스크립트를 생성하며, 이때 --input_file 플래그로 API JSON 경로를 지정한다 [35, 36].
Lou@blog Python 코드:urllib와 websocket을 사용하여 API JSON의 특정 노드 ID(예: #37 TextInput)의 inputs.text 값을 교체한 후 서버에 요청을 보내는 구조를 구현하였다 [16, 37].
✅ 검증 상태 및 신뢰도
상태: draft
검증 단계: conceptual (실제 적용 사례 다수 발견됨에 따라 추후 applied/validated 승격 가능)
출처 신뢰도: B (공식 문서 및 실제 오픈소스 프로젝트의 README/구현 코드를 바탕으로 함)
중복 검사 결과: 신규 생성 (New discovery)
📝 변경 이력 (Change history)
2026-05-19: Initial draft generated via Datacollector_MAC P-Reinforce engine.
