API Reference

Job 생성

완성된 ComfyUI API-format prompt로 비동기 Job 한 건을 생성합니다.

POST/v1/api/job/comfy-prompt

요청 예제

bash

curl --request POST   --url "$NORDY_BASE_URL/v1/api/job/comfy-prompt"   --header "api-key: $NORDY_API_KEY"   --header "content-type: application/json"   --data-binary @request.json

성공 응답202 Accepted

JSON

{
  "id": "68abcdef0123456789abcdef",
  "user_metadata": {},
  "status": "queued",
  "createdAt": "2026-08-26T00:00:00.000Z",
  "startedAt": null,
  "completedAt": null,
  "outputs": null,
  "error": null
}

인증

api-keystring필수

사용자 API key를 api-key request header에 넣습니다.

요청 본문

Content-Type: application/json

promptobjectbody필수: Node ID를 key로 사용하는 API 형식의 프롬프트입니다.
prompt.<nodeId>.class_typestringbody필수: ComfyUI node class 이름입니다.
prompt.<nodeId>.inputsobjectbody필수: Node에 전달할 input이며 연결은 [sourceNodeId, outputIndex] 형식입니다.
user_metadataobjectbody선택: 애플리케이션의 기록과 Job을 연결하는 사용자 데이터입니다.

입력 제한

요청 JSON은 최대 50 MiB이며 프롬프트는 노드 1~1,024개를 포함할 수 있습니다.
프롬프트 구조는 중첩 깊이 32단계, 전체 속성 16,384개, 배열별 원소 4,096개로 제한됩니다.
프롬프트의 문자열은 UTF-8 기준 64 KiB, 키는 1,024바이트 이하입니다. 정수는 -9,007,199,254,740,991 이상 9,007,199,254,740,991 이하로 입력하세요.
user_metadata는 최대 32개의 키, 전체 크기 8 KiB까지 허용합니다.
메타데이터 키는 영문 또는 숫자로 시작하는 최대 64자입니다. 영문, 숫자, 밑줄, 마침표, 하이픈을 사용할 수 있으며 __proto__, prototype, constructor는 예약된 이름입니다.
메타데이터 값은 문자열, 숫자, 참·거짓, null을 사용할 수 있습니다. 중첩 객체와 배열은 지원하지 않으며 문자열은 UTF-8 기준 1,024바이트 이하입니다.
메타데이터 숫자는 -9,007,199,254,740,991 이상 9,007,199,254,740,991 이하의 유한한 값이어야 합니다. -0 대신 0을 사용하세요.

성공 응답

202 Accepted queued·processing 응답에는 Retry-After: 5가 포함됩니다.

idstringresponse필수: Job ID입니다.
user_metadataobjectresponse필수: Job 생성 시 전달한 metadata이며 생략하면 {}입니다.
statusqueued | processing | succeeded | failed | canceledresponse필수: 현재 Job 상태입니다.
createdAtdate-timeresponse필수: Job 생성 시각입니다.
startedAtdate-timeresponse필수nullable: 실행 시작 시각이며 값이 없으면 null입니다.
completedAtdate-timeresponse필수nullable: 최종 완료 시각이며 값이 없으면 null입니다.
outputsarrayresponse필수nullable: succeeded Job의 미만료 결과입니다. 모두 만료되면 []이며 Job은 계속 조회할 수 있습니다. 그 외 상태는 null입니다.
outputs[].idstringresponse필수: API Output Asset ID입니다.
outputs[].urlstringresponse필수: 생성된 파일 URL입니다.
outputs[].kindimage | video | audio | model3dresponse필수: Output media kind입니다.
outputs[].expiresAtdate-timeresponse필수: 이 결과가 생성된 시점으로부터 7일 후의 만료 시각입니다. 그 전에 파일을 다운로드하세요.
errorobjectresponse필수nullable: failed·canceled Job의 최종 오류이며 그 외에는 null입니다.
error.codeenumresponse필수: INVALID_INPUT, INSUFFICIENT_CREDIT, EXECUTION_TIMEOUT, WORKER_UNAVAILABLE, EXECUTION_FAILED, JOB_CANCELED 중 하나입니다.
error.messagestringresponse필수: 공개 오류 메시지입니다.
error.detailsobjectresponse선택: ComfyUI 원본 validation 데이터입니다. 가능한 경우 INVALID_INPUT에만 포함됩니다.
error.details.errorobjectresponse필수: ComfyUI prompt의 유효성 검사 오류입니다.
error.details.node_errorsobjectresponse필수: Node ID별 ComfyUI 유효성 검사 오류입니다.

참고

Job 생성에는 일일 한도가 있습니다.
최상위에는 prompt와 선택적인 user_metadata만 허용됩니다.
prompt나 user_metadata가 같아도 접수된 요청마다 새 Job이 생성됩니다. 시간 초과나 응답 유실 시에는 자동 재제출하지 말고 저장한 ID나 최근 Job 목록을 먼저 확인하세요.
ComfyUI node 값 검증 오류는 생성 이후 failed Job의 INVALID_INPUT으로 나타날 수 있습니다.

응답과 오류

Status	Code	설명
429	DAILY_JOB_LIMIT_EXCEEDED	생성 한도에 도달했습니다. 초기화된 후 다시 시도하세요.
400	INVALID_JSON, INVALID_INPUT	JSON, prompt 또는 metadata가 유효하지 않습니다.
400	MULTIPLE_AUTH_CREDENTIALS	로그인 쿠키를 제외하고 api-key header만 보내세요.
401	AUTHENTICATION_REQUIRED	API key가 없거나 일치하지 않습니다.
402	INSUFFICIENT_CREDIT	Job을 생성할 credit이 부족합니다.
403	USER_SUSPENDED, PRO_SUBSCRIPTION_REQUIRED, INVALID_INPUT	계정이 정지되었거나, Pro 구독이 활성화되어 있지 않거나, API 이용이 제한된 상태입니다.
413	REQUEST_BODY_TOO_LARGE	JSON body가 최대 크기인 50 MiB를 초과했습니다.
415	UNSUPPORTED_MEDIA_TYPE	Content-Type이 application/json이 아닙니다.
500	INTERNAL_ERROR	서버 내부 오류입니다.