ComfyUI JSON, Workflow와 API Format 차이

ComfyUI를 사용하다 보면 같은.json 파일인데도 용도가 전혀 다른 경우가 있다. 하나는 노드 위치와 연결 상태까지 저장해 다시 화면에 불러오는 Workflow JSON이고, 다른 하나는 ComfyUI 서버에 실행 요청을 보내기 위한 API Format JSON이다.

특히 Python으로 ComfyUI 자동화를 시작할 때 이 차이를 모르고 일반 workflow JSON을 그대로 /prompt에 보내면 실행되지 않는 경우가 많다. 핵심은 JSON이라는 확장자가 아니라 내부에 어떤 구조가 들어 있는지를 보는 것이다.

json에서 가장 먼저 볼 변화

ComfyUI Workflow JSON은 화면을 복원하는 파일이다

일반적으로 ComfyUI에서 워크플로우를 저장하면 만들어지는 JSON은 그래프 자체를 보존한다. 최신 공식 Workflow JSON 사양에서도 nodes, state, version 같은 워크플로우 상태를 표현하는 구조가 정의되어 있다.

여기에는 어떤 노드가 존재하는지뿐 아니라 UI에서 다시 그래프를 구성하는 데 필요한 정보가 포함될 수 있다. 즉 사람이 ComfyUI 화면에서 작업하던 상태를 저장하고 다시 불러오는 목적에 가깝다.

JSON에서 nodes가 보인다면 확인할 것

파일을 텍스트 편집기로 열었을 때 최상위에 nodes 배열이 있고 각각의 노드에 ID와 위치, 입력 및 출력 관련 정보가 들어 있다면 일반 Workflow JSON일 가능성이 높다.

이 형식은 파일을 ComfyUI로 드래그해 워크플로우를 복원할 때 유용하다. 반대로 이것을 그대로 Python에서 실행용 payload로 보내는 것은 다른 문제다.

자동화 프로그램을 만들 때는 먼저 자신이 가진 JSON이 '편집용 그래프'인지 '실행용 그래프'인지 구분해야 한다. 파일명이 workflow.json인지 여부만으로는 판단할 수 없고 내부 구조를 직접 보는 편이 확실하다.

API Format JSON은 노드 ID가 최상위 키가 된다

json가 ComfyUI 워크플로우에 미치는 영향

ComfyUI 공식 Cloud API 문서는 API가 실행할 워크플로우를 이른바 API format으로 받는다고 설명한다. 이 구조에서는 "3", "6", "12"처럼 노드 ID가 JSON 객체의 최상위 키로 배치된다.

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

각 노드 내부에는 대표적으로 class_type과 inputs가 들어간다. 연결된 입력은 상위 노드 ID와 출력 슬롯을 가리키는 형태로 표현되기 때문에, 서버는 UI 좌표를 복원하지 않아도 어떤 노드를 어떤 순서와 연결 관계로 실행해야 하는지 파악할 수 있다.

class_type과 inputs가 중요한 이유

class_type은 어떤 ComfyUI 노드를 실행할지 지정한다. inputs에는 프롬프트, seed, 모델명 같은 실제 입력값과 다른 노드에서 전달되는 연결 정보가 들어간다.

따라서 자동 생성 프로그램에서 프롬프트만 바꾸거나 seed를 매번 변경하고 싶다면 API Format JSON의 특정 inputs 값을 수정하는 방식이 훨씬 다루기 쉽다.

예를 들어 자동화 스크립트가 특정 노드의 inputs.seed 또는 텍스트 입력을 바꾼 뒤 서버에 보내는 구조를 만들 수 있다. ComfyUI 공식 API 예제 역시 API Format workflow를 읽은 뒤 특정 노드의 입력값을 수정해 제출하는 방식을 보여준다.

JSON을 API에 보낼 때 한 단계가 더 있다

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

API Format JSON을 만들었다고 해서 파일 전체를 아무 형태로나 POST하면 되는 것은 아니다. ComfyUI의 실행 요청에서는 workflow 객체가 요청 payload의 prompt에 들어간다.

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

즉 개념적으로는 '실행 가능한 노드 그래프'를 만든 다음 그것을 prompt 값으로 감싸 서버의 prompt endpoint에 제출하는 구조다. 정상적으로 접수되면 서버는 실행을 식별할 수 있는 prompt_id를 반환한다.

이 부분 때문에 일반 Workflow JSON, API Format workflow, 실제 HTTP 요청 payload를 모두 하나의 'ComfyUI JSON'으로 생각하면 자동화 코드를 구성할 때 혼란이 생긴다.

API를 이용해 이미지를 여러 장 자동 생성하거나 외부 프로그램에서 ComfyUI를 제어하려는 경우에는 이 세 단계를 분리해서 보는 편이 좋다. 그래프를 편집하는 파일과 실행할 그래프, 그리고 서버에 전달하는 요청 객체는 서로 같은 역할이 아니다.

목적에 따라 어떤 JSON을 사용해야 하는가

ComfyUI 화면에서 워크플로우를 백업하고 다시 수정하는 것이 목적이라면 일반 Workflow JSON이 적합하다. 노드 배치와 그래프를 다시 불러와 작업을 이어가는 용도이기 때문이다.

반면 Python 프로그램에서 prompt와 seed를 바꾸면서 반복 실행하거나 외부 서비스와 ComfyUI를 연결하려는 목적이라면 API Format을 기준으로 잡는 것이 맞다. 공식 문서에서도 API 실행에는 노드 ID를 키로 갖는 API format workflow를 사용한다.

자동화 전에 가장 먼저 볼 부분

실제로 적용할 때 체크할 점

가지고 있는 JSON을 텍스트 편집기로 열고 최상위 구조부터 확인하면 된다.

nodes 배열을 중심으로 구성되어 있다 → Workflow JSON인지 확인

"3", "6" 같은 노드 ID 아래 class_type, inputs가 있다 → API Format인지 확인

최종 HTTP 요청에서는 실행 그래프가 prompt 객체에 들어가는지 확인

이 세 가지만 구분해도 "JSON은 정상인데 ComfyUI API에서 실행되지 않는다"는 문제를 상당 부분 빠르게 좁힐 수 있다.

마지막 확인

ComfyUI에서 JSON이라는 말은 하나의 형식을 의미하지 않는다. 화면을 저장하는 Workflow JSON과 서버가 실행하는 API Format JSON을 먼저 나눠서 생각해야 한다.

외부 자동화를 만들고 있다면 현재 JSON을 열어 최상위에 nodes가 있는지, 노드 ID별 class_type과 inputs가 있는지부터 확인하자. 그 다음 실행용 JSON을 prompt에 넣어 서버로 전달하는 구조를 잡으면 된다.