ComfyUI란 무엇이고 API 모드로 어떻게 여는가

ComfyUI가 뭔가요?

ComfyUI는 이미지를 AI로 생성하는 오픈소스 도구입니다. 특이한 점은 '노드(node) 기반 인터페이스'를 쓴다는 것입니다. 화면에 블록을 연결하듯 이미지 생성 파이프라인을 직접 조립할 수 있습니다. "텍스트를 받아서 → CLIP 인코더에 넣고 → 디노이저(KSampler)로 이미지를 만들고 → VAE로 디코딩해서 → 저장한다" 같은 흐름을 시각적으로 만들 수 있습니다.

이 가이드에서 사용하는 모델은 z_image_turbo_nvfp4.safetensors입니다. 이것은 AuraFlow 아키텍처 기반 모델입니다. SDXL이나 SD 1.5와는 완전히 다른 구조입니다. SDXL이 UNet 구조를 쓴다면, AuraFlow는 Diffusion Transformer(DiT) 구조를 씁니다. 그래서 KSampler 앞에 ModelSamplingAuraFlow 노드를 넣어야 하고, 텍스트 인코더도 일반 CLIP이 아니라 Qwen 기반 인코더(qwen_3_4b.safetensors)를 사용합니다. 잘못된 모델 구조로 워크플로우를 만들면 에러가 납니다.

실제 설치 위치

이 가이드의 ComfyUI 설치 위치는 E:AI입니다.

E:AI\n├── ComfyUI              ← ComfyUI 소스 코드
│   ├── main.py
│   ├── models\n│   │   ├── unet         ← z_image_turbo_nvfp4.safetensors 위치
│   │   ├── vae          ← ae.safetensors 위치
│   │   └── clip         ← qwen_3_4b.safetensors 위치
│   └── output           ← ComfyUI가 생성 이미지를 먼저 저장하는 폴더
└── python_embeded       ← ComfyUI 전용 내장 Python
    └── python.exe

ComfyUI는 시스템 Python을 쓰지 않습니다. E:AIpython_embededpython.exe라는 내장(embeded) Python을 씁니다. 이 Python에는 ComfyUI가 필요로 하는 패키지들이 미리 설치되어 있습니다. 시스템에 Python이 없어도 ComfyUI가 돌아가는 이유가 이것입니다.

ComfyUI 시작 — restart-comfy.ps1

ComfyUI를 매번 수동으로 실행하면 불편합니다. 이 프로젝트에서는 D:\016_CardNewio estart-comfy.ps1이라는 스크립트로 ComfyUI를 (재)시작합니다.

Stop-Process -Name python -Force -ErrorAction SilentlyContinue
Start-Sleep -Seconds 2
Start-Process -FilePath 'E:AIpython_embededpython.exe' `
    -ArgumentList @('-s','ComfyUImain.py','--windows-standalone-build') `
    -WorkingDirectory 'E:AI' `
    -WindowStyle Minimized
Start-Sleep -Seconds 20
Invoke-RestMethod -Method Get -Uri 'http://127.0.0.1:8188/system_stats' | ConvertTo-Json -Depth 3

각 줄을 설명합니다.

Stop-Process -Name python -Force -ErrorAction SilentlyContinue 이미 실행 중인 python 프로세스를 강제 종료합니다. 이전 ComfyUI 인스턴스가 살아있으면 포트가 충돌하기 때문입니다. SilentlyContinue는 프로세스가 없어도 에러 없이 넘어가게 합니다.

Start-Sleep -Seconds 2 프로세스 종료가 완전히 끝날 때까지 2초를 기다립니다. 포트가 해제되는 시간을 줍니다.

Start-Process ... -WindowStyle Minimized ComfyUI를 백그라운드(최소화 창)로 실행합니다. -WorkingDirectory 'E:AI'는 작업 디렉토리를 E:AI로 지정합니다. ComfyUI가 상대경로로 모델 파일을 찾기 때문에 작업 디렉토리가 맞아야 합니다.

Start-Sleep -Seconds 20 ComfyUI 서버가 완전히 뜰 때까지 20초를 기다립니다. 모델이 크면 더 오래 걸릴 수 있습니다. GPU 메모리에 모델을 올리는 데 시간이 필요합니다.

Invoke-RestMethod ... /system_stats ComfyUI가 정상 기동됐는지 확인합니다. 응답이 오면 서버가 준비된 것입니다. 응답 내용에는 GPU 정보, VRAM 사용량, CUDA 버전 등이 포함됩니다.

이 스크립트를 SSH로 원격 실행하면 Linux에서도 ComfyUI를 재시작할 수 있습니다. SSH 키 설정 방법은 15단계에서 자세히 다룹니다.

ssh -i /root/.ssh/id_ed25519_cardnews reedoc@<WINDOWS_IP> \
  'powershell -NoProfile -ExecutionPolicy Bypass -File "D:\\016_CardNew\io\restart-comfy.ps1"'

ComfyUI API 엔드포인트

ComfyUI는 서버를 켜면 자동으로 HTTP API 서버도 같이 열립니다. 별도 설정 없이 세 개의 엔드포인트를 씁니다.

POST http://127.0.0.1:8188/prompt 이미지 생성을 시작하는 엔드포인트입니다. 워크플로우 JSON을 Body에 담아서 보내면 됩니다. 응답으로 prompt_id(UUID 형식)가 돌아옵니다.

요청 Body:
{
  "prompt": { ...워크플로우 JSON 전체... }
}

응답:
{
  "prompt_id": "626d4d7c-6955-4577-a2b6-80d4cd80c172",
  "number": 1,
  "node_errors": {}
}

GET http://127.0.0.1:8188/history/{prompt_id} 이미지 생성 상태와 결과를 조회하는 엔드포인트입니다. 생성 중에는 빈 객체가 옵니다. 완료되면 outputs 안에 이미지 파일 정보가 담깁니다.

응답 (완료 시):
{
  "626d4d7c-...": {
    "outputs": {
      "9": {
        "images": [
          {
            "filename": "Z_Image_Turbo/27-02-2026/image_00001_.png",
            "subfolder": "",
            "type": "output"
          }
        ]
      }
    }
  }
}

GET http://127.0.0.1:8188/view?filename=...&subfolder=...&type=output 실제 이미지 파일을 다운로드하는 엔드포인트입니다. history에서 얻은 filename, subfolder, type 값을 쿼리 파라미터로 넣으면 이미지 바이너리를 돌려줍니다.

GET http://127.0.0.1:8188/system_stats 서버 상태 확인용입니다. 응답에 CUDA 버전, GPU 이름, VRAM 사용량이 포함됩니다. ComfyUI가 정상 실행 중인지 확인할 때 씁니다.

워크플로우 API 포맷으로 내보내기

ComfyUI 워크플로우를 저장하는 방법은 두 가지입니다. 일반 Save와 API Format Save입니다. 이 두 가지는 완전히 다른 포맷입니다.

일반 Save는 ComfyUI GUI가 읽는 포맷입니다. API로 보낼 수 없습니다.

API Format은 노드 ID를 키로 쓰는 플랫한 JSON입니다. 이것만 /prompt 엔드포인트에서 받아줍니다.

API Format으로 내보내는 방법입니다.

1단계: ComfyUI 화면 오른쪽 위 톱니바퀴 아이콘을 클릭합니다.

2단계: 설정 창에서 Enable Dev mode Options를 찾아 체크합니다.

3단계: 설정 창을 닫으면 화면 상단 버튼 바에 Save (API Format) 버튼이 새로 생깁니다.

4단계: 이 버튼을 클릭해서 comfy_workflow.json으로 저장합니다.

저장된 파일 구조는 이렇습니다. 숫자 문자열이 각 노드의 ID입니다.

{
  "3": { "class_type": "KSampler", "inputs": { ... } },
  "6": { "class_type": "CLIPTextEncode", "inputs": { "text": "...", "clip": ["18",0] } },
  "7": { "class_type": "CLIPTextEncode", "inputs": { "text": "...", "clip": ["18",0] } }
}

worker.ps1은 이 파일에서 노드 ID "6"(Positive Prompt)과 "7"(Negative Prompt)의 inputs.text 값을 job.json에서 받은 프롬프트로 교체합니다.

이 가이드에서 사용하는 워크플로우 노드 구성

이 프로젝트의 실제 comfy_workflow.json은 총 10개 노드로 구성됩니다.

출력 해상도가 1080x1080인 이유는 카드뉴스 제작을 위해서입니다. SNS 카드뉴스의 표준 비율인 1:1 정사각형입니다.

cfg=1은 매우 낮은 값입니다. 일반적인 Stable Diffusion에서는 7~10을 씁니다. z_image_turbo는 Flow Matching 기반이라 cfg=1에서도 좋은 결과가 나옵니다. 높게 설정하면 오히려 품질이 떨어집니다.

steps=15도 일반 모델보다 적습니다. Turbo 계열 모델은 소수의 스텝으로도 고품질 이미지를 만들도록 학습되어 있기 때문입니다.

다음 단계에서 할 것

ComfyUI가 무엇인지, 어디에 설치되어 있는지, API가 어떻게 동작하는지, 워크플로우를 어떻게 내보내는지 이해했습니다. 다음 단계에서는 실제 파이프라인 폴더 구조를 만들고 각 파일의 역할을 자세히 살펴봅니다.