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

ComfyUI가 뭔가요?

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

이 가이드에서 사용하는 모델은 z_image_turbo_nvfp4.safetensors입니다. 이것은 Alibaba Tongyi Lab이 2025년 11월 출시한 S3-DiT(Scalable Single-Stream DiT) 아키텍처 기반 모델입니다. SDXL이나 SD 1.5와는 완전히 다른 구조입니다. SDXL이 UNet 구조를 쓴다면, z_image_turbo는 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는 프로세스가 없어도 에러 없이 넘어가게 합니다. 주의: 이름이 python인 모든 프로세스를 종료합니다. ComfyUI 외에 다른 Python 프로그램이 실행 중이라면 함께 종료됩니다. 이 점을 감안하고 사용합니다.

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 키 설정 방법은 4단계에서 자세히 다룹니다.

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가 어떻게 동작하는지, 워크플로우를 어떻게 내보내는지 이해했습니다. 다음 단계에서는 실제 파이프라인 폴더 구조를 만들고 각 파일의 역할을 자세히 살펴봅니다.