ComfyUI via JSON 사용법, API로 워크플로우 실행하기

ComfyUI를 자동화하다 보면 화면에서 Queue 버튼을 누르는 대신 JSON을 통해 workflow를 실행하고 싶을 때가 있다. 이 경우 핵심은 일반 Workflow JSON을 그대로 보내는 것이 아니라 API 실행용 구조를 준비해 /prompt로 전달하는 것이다.

ComfyUI 공식 API 예제도 JSON 형태의 workflow를 Python에서 읽고, 이를 prompt라는 key 아래에 넣어 서버로 전송하는 방식을 사용한다. 즉 "via JSON"으로 ComfyUI를 실행한다는 것은 JSON 파일 자체를 여는 것이 아니라 JSON 데이터를 HTTP 요청으로 backend에 전달하는 흐름에 가깝다.

via json 사용법에서 가장 먼저 볼 변화

먼저 Workflow를 API Format으로 준비한다

ComfyUI 화면에서 저장하는 일반 workflow와 API 실행용 JSON은 목적이 다르다. API 예제에서 사용하는 구조는 node ID가 최상위 key가 되고, 각 node 안에 class_type과 inputs가 들어가는 형태다.

예를 들어 KSampler node라면 하나의 node ID 아래에 sampler_name, scheduler, seed, steps 같은 입력값이 들어갈 수 있다. 다른 node의 출력을 참조하는 입력은 연결된 node ID와 output index를 이용해 표현된다.

일반 Workflow JSON과 혼동하지 않는다

ComfyUI UI에서 저장한 workflow가 화면에서 정상적으로 열린다고 해서 그대로 /prompt에 보낼 수 있다는 뜻은 아니다. API 호출에서는 실행용 API Format workflow를 기준으로 준비해야 한다.

공식 기본 API 예제에서도 이 구조를 "ComfyUI api prompt format"으로 설명하고 있다. 자동화 목적이라면 먼저 API용 JSON을 확보한 뒤 다음 단계로 넘어가는 편이 단순하다.

이 단계에서 중요한 것은 JSON 문법보다 workflow 형식이다. JSON 자체가 정상이어도 실행용 구조가 아니라면 backend가 기대하는 prompt 형식과 맞지 않을 수 있다.

JSON은 prompt 객체 안에 넣어서 보낸다

API Format workflow를 준비했다면 그 JSON 객체 전체를 HTTP body의 prompt key 아래에 넣는다.

via json 사용법가 ComfyUI 워크플로우에 미치는 영향

개념적으로는 workflow 자체가 최상위 요청 body가 되는 것이 아니라, 요청 body 안에 prompt라는 필드가 있고 그 값으로 workflow JSON이 들어가는 구조다.

기존 방식과 비교해야 할 부분

Python 공식 예제에서는 먼저 p = {"prompt": prompt} 형태의 object를 만든다. 이후 이를 JSON 문자열로 직렬화하고 UTF-8 byte 데이터로 변환해 요청 body로 사용한다.

json.dumps는 전송 가능한 형태로 바꾸는 단계다

Python dictionary 상태의 workflow를 HTTP body로 바로 보내는 것이 아니라 JSON 문자열로 직렬화하는 단계가 필요할 수 있다.

공식 예제에서는 json.dumps()를 사용해 요청 객체를 JSON 문자열로 바꾼 뒤 UTF-8로 encode한다. 이렇게 만들어진 데이터가 ComfyUI backend로 전달된다.

따라서 via JSON 실행 과정은 workflow 준비 → prompt 객체 구성 → JSON 직렬화 → HTTP 전송 순서로 보면 이해하기 쉽다.

로컬 ComfyUI에서는 /prompt로 전송한다

기본 로컬 ComfyUI API 예제는 http://127.0.0.1:8188/prompt를 대상으로 요청을 보낸다. 즉 기본 로컬 환경이라면 실행 중인 ComfyUI backend의 /prompt endpoint가 workflow 실행 요청을 받는다.

성능과 결과 품질에서 확인할 차이

ComfyUI 서버가 다른 IP나 port에서 실행 중이라면 당연히 해당 주소에 맞춰 변경해야 한다. 예를 들어 --port 옵션으로 다른 포트를 사용했다면 API 요청 주소 역시 같은 포트를 사용해야 한다.

워크플로우 구성에서 놓치기 쉬운 부분

요청을 받은 backend는 workflow를 queue에 넣어 실행한다. WebSocket API 예제에서는 이때 받은 prompt_id를 기준으로 어느 작업이 실행 중인지 추적하는 구조도 사용한다.

단순히 workflow를 한 번 실행하는 목적이라면 POST 요청까지만 구현해도 시작할 수 있다. 진행 상태나 결과 파일까지 자동으로 처리하려면 prompt_id, WebSocket, history 같은 단계를 추가하게 된다.

실행 전에 JSON의 node input을 바꿀 수 있다

API Format workflow를 JSON으로 다루는 장점 중 하나는 전송 전에 특정 node의 입력값을 프로그램에서 변경하기 쉽다는 점이다.

공식 API 예제에서도 CLIPTextEncode의 text 값을 바꾸거나 KSampler의 seed 값을 수정한 다음 동일한 workflow를 queue에 넣는다. 매번 새로운 workflow를 만들지 않고 기본 JSON 하나를 템플릿처럼 사용할 수 있는 이유다.

node ID와 inputs 경로를 정확히 알아야 한다

예를 들어 prompt를 바꾸려면 해당 CLIPTextEncode node의 ID를 알고 그 node의 inputs 안에 있는 text를 변경해야 한다.

실제로 적용할 때 체크할 점

seed도 마찬가지다. KSampler node ID를 찾은 뒤 inputs 아래의 seed 값을 수정한다.

따라서 자동화를 만들 때는 JSON 전체를 문자열 치환하기보다 node ID → inputs → 원하는 key 경로로 값을 바꾸는 편이 구조적으로 이해하기 쉽다.

Cloud API와 로컬 API 주소는 구분한다

로컬 ComfyUI 예제에서는 /prompt를 사용하지만 Comfy Cloud API 문서에서는 /api/prompt endpoint를 사용한다. Cloud에서는 API key 인증도 추가된다.

따라서 인터넷에서 예제를 가져왔을 때 /prompt와 /api/prompt가 섞여 있다면 어느 환경을 대상으로 한 코드인지 먼저 확인해야 한다.

로컬에서 실행 중인 일반 ComfyUI backend를 자동화하는 것인지, Comfy Cloud에 workflow를 제출하는 것인지에 따라 endpoint와 인증 조건이 달라진다.

마지막 확인

ComfyUI를 via JSON 방식으로 실행하려면 먼저 API Format workflow를 준비하자. 그 JSON을 prompt 객체 안에 넣고 로컬 backend의 /prompt로 POST하면 기본적인 자동 실행 흐름을 만들 수 있다.

이 방식이 정상적으로 동작한 뒤에는 node의 text나 seed를 실행 전에 바꾸는 기능을 추가하면 된다. 이후 작업 상태까지 추적해야 한다면 prompt_id와 WebSocket, history 처리를 단계적으로 붙이는 것이 가장 깔끔하다.