Skip to main content
POST /v2/models/{provider}/{model}는 모델이 끝날 때까지 연결을 유지합니다. 대기 중 전달은 동일한 모델 ID와 동일한 네이티브 요청 본문을 사용하지만, Router가 실행을 수락하는 즉시 반환합니다. request_id를 곧바로 돌려받고, 결과가 준비되면 같은 프로세스에서든 다른 프로세스에서든 수집하면 됩니다. 동기 경로는 10분으로 제한됩니다. Router의 기본 데드라인은 배포별로 구성할 수 있습니다. 이에 도달한 동기 호출은 공급자가 아직 작업 중인지와 무관하게 504 / deadline_exceeded와 함께 종료됩니다. 실행이 데드라인을 초과할 수 있거나 호출자가 그만큼 오래 연결을 열어 둘 수 없다면 실행 대기열을 사용하세요. 데드라인이 과금에 대해 알려주는 것과 알려주지 않는 것은 서버 데드라인에서 호출이 종료됨을 참조하세요. 생성이 유지할 수 있는 연결보다 오래 걸릴 수 있을 때, 웹 요청이 지금 반환되어야 할 때, 한 프로세스에서 제출하고 다른 프로세스에서 수집할 때, 또는 여러 생성을 동시에 진행하고 싶을 때 실행 대기열을 사용하세요. 순서, 수락, 재시도, 타임아웃, 과금 및 만료는 모두 서버에서 결정됩니다. SDK는 그 위에 폴링과 편의 기능을 더할 뿐, 그 외에는 아무것도 하지 않습니다.

전달 모드 선택

SDK(comfy-sdk 및 @comfyorg/sdk, 0.3.0 이상)는 run 옆에 실행 대기열을 세 가지 메서드로 노출합니다:
  • **submit(model, body)**는 요청을 보내고 즉시 핸들을 반환합니다. 핸들은 status(), get(), cancel() 및 이벤트 이터레이터(Python에서는 iter_events(), TypeScript에서는 events())를 제공합니다.
  • **subscribe(model, body, ...)**는 진행률 콜백과 함께 제출, 폴링, 수집을 한 번의 호출로 수행합니다.
  • **handle(model, request_id)**는 호출 없이 두 ID만으로 다른 프로세스에서 핸들을 재구성합니다.
두 ID 모두 요청을 지정하는 데 쓰이므로 어디서나 필요합니다: 경로는 /v2/models/{provider}/{model}/requests/{request_id}입니다.
여기서 events()는 Comfy Cloud 클라이언트의 job.events()가 아닙니다. 이것은 상태 경로를 폴링하여 Router 요청에 대한 실행 대기열 관측값(상태와 대기열 위치)을 산출합니다. 클라우드 쪽은 진행률, 미리보기, 출력을 전달하는 ComfyUI 워크플로 작업의 실시간 SSE 스트림입니다. subscribe()는 또 다른 세 번째 것입니다. 이터레이터가 전혀 아니고, 제출, 폴링, 수집을 하나의 호출로 접어 놓은 것입니다. events()는 subscribe()가 아닙니다를 참고하세요.

실행 대기열 라우트

status는 IN_QUEUE, IN_PROGRESS, COMPLETED 중 하나입니다. 별도의 실패 또는 취소됨 상태는 없습니다. 성공하지 못한 요청은 error_type을 포함한 COMPLETED이므로, 네 번째 상태 값을 기준으로 분기하지 말고 해당 필드의 존재 여부를 기준으로 분기하세요. SDK가 이를 대신 처리해 줍니다. get()은 실패를 결과로 돌려주는 대신 타입이 지정된 Router 오류를 발생시키거나 reject합니다. 진행 이벤트, webhook, 우선순위 수준은 없습니다. 요청을 추적하는 방법은 상태 라우트입니다. API 레퍼런스에 각 라우트의 전체 계약이 나와 있습니다.

요청 제출 및 수집

quickstart에서 보내는 것과 동일한 요청을 실행 대기열에 넣고 이미지를 수집합니다. 먼저 키를 COMFY_API_KEY로 내보내세요.
모든 모델 페이지에는 동기식 스니펫 옆에, 각 모델에 맞는 이 형태가 나중에 실행 대기열에 넣고 수집 아래에 실려 있습니다.

진행 상황을 따라가며 한 번에 수집

기다리면서 동시에 진행 상황도 보여주고 싶다면, subscribe가 제출, 폴링, 수집을 하나의 호출로 묶어 줍니다:
타임아웃은 클라이언트 측 제한이며 서버 측 의미는 없습니다. 타임아웃이 되면 subscribe는 예외를 발생시키기 전에 최선의 노력으로 한 번 취소를 시도합니다. 취소는 아직 실행을 시작하지 않은 요청에만 효과가 있습니다. 파트너에서 이미 진행 중인 생성은 누군가 수집하든 하지 않든 완료되고 과금됩니다. 요청이 호출자보다 오래 살아야 할 때는 submit을 사용하세요.

다른 프로세스에서 수집

request_id를 모델 ID 옆에 저장하세요. 핸들을 다시 만들려면 둘 다 필요하며, 사용할 때까지 아무 호출도 이루어지지 않습니다.

상태 확인 또는 취소

status()는 한 번의 폴링이며 현재 상태를 반환합니다. cancel()은 아직 완료되지 않은 요청을 중지하도록 서버에 요청합니다. 이는 요청일 뿐 보장이 아닙니다. 파트너에 이미 전달된 실행은 어쨌든 완료될 수 있으며, 진실은 다음 status()가 알려줍니다.

비동기 Python

AsyncComfy는 모든 이름, 인수, 인수 순서를 그대로 반영합니다. run_async가 없는 것과 같은 이유로 submit_async도 없습니다.

SDK가 발생시키는 오류

성공하지 못하고 완료된 요청은 error_type과 함께 COMPLETED로 보고됩니다. get()과 subscribe()는 이를 해당 버킷의 타입이 지정된 Router 오류로 변환합니다. Python에서는 comfy_sdk.router_exceptions의 클래스이고, TypeScript에서는 routerErrors.*입니다. 이벤트 반복자는 이 경우 예외를 발생시키지 않습니다. 이는 실행 대기열 진행 상황을 보여주는 뷰이기 때문입니다. error_type을 가진 완료는 마지막 관측으로 산출되고, 수집은 get()이 담당합니다. 제출 시 403 not_enabled는 NotEnabled로 도착하며 터미널이므로 SDK는 이를 재시도하지 않습니다.

실행 대기열 응답 형태

제출, 201. 이 시점에서 status는 항상 IN_QUEUE입니다. 세 개의 URL은 절대 경로이며 제출과 동일한 키로 인증됩니다.
request_id는 제출의 X-Comfy-Request-Id 헤더 값이기도 합니다. 옆에 모델 ID를 함께 보관하세요. 요청은 두 값 모두로 특정됩니다. 상태, 200. 현재 상태와 함께 같은 형태로 돌아옵니다. queue_position은 내 요청보다 앞에 있는 요청 수를 세며, 실행이 맨 앞에 도달하면 0이 됩니다. 이 응답의 Retry-After는 다시 폴링할 가치가 있는 시점에 대한 Router의 추정치입니다. 이는 힌트일 뿐 제약이 아니며, 대기열 맨 뒤의 요청은 이미 실행 중인 요청보다 더 오래 기다리라는 안내를 받습니다. 더 빠르게 폴링해도 더 일찍 알 수 있는 것은 없고 자신의 rate-limit 허용량만 소모합니다.
성공하지 못하고 완료된 요청은 error_type과 함께 COMPLETED이며, 결과 조회가 X-Comfy-Error-Type에 담는 것과 동일한 포괄적 버킷을 전달합니다. 이 필드는 성공 시 null이 아니라 아예 존재하지 않습니다.
결과. 200은 모델 자체의 네이티브 출력을 담으며, 동일한 모델과 입력에 대해 동기 경로가 반환하는 것과 바이트 단위로 동일하고, 공급자 자체의 Content-Type을 따릅니다. 요청이 끝나지 않은 동안에는 위의 상태 본문과 함께 202로 응답하므로, 결과 URL만 폴링하는 클라이언트는 한 가지 타입만 파싱하면 됩니다. 실패한 요청은 X-Comfy-Error-Type이 설정된 오류 응답으로 돌아오며, 동기 경로와 동일한 버킷입니다. 취소. CANCELLATION_REQUESTED와 함께 오는 202는 요청이 수락되었음을 의미할 뿐, 실행이 중단되었음을 의미하지 않습니다. 파트너에서 이미 진행 중인 실행은 그대로 완료될 수 있으며, 완료된 파트너 생성은 누군가 수집하든 하지 않든 과금됩니다. 이후 상태를 확인하세요. 취소가 실제로 반영된 경우 error_type: cancelled와 함께 COMPLETED로 나타납니다. 실행되기 전에 만료된 요청은 같은 방식으로 queue_timeout을 표시합니다. 이미 완료된 요청은 ALREADY_COMPLETED와 함께 409로 응답합니다.

멱등성 및 과금

  • 동기 경로와 동일한 과금. 공급자가 Comfy에 과금할 때 과금됩니다. 실행 대기열에서 대기한 시간은 과금되지 않습니다.
  • 제출당 하나의 Idempotency-Key. SDK는 submit 호출마다 새로운 키를 생성하므로, 같은 입력을 의도적으로 두 번 제출하면 두 개의 요청이 됩니다. 동일한 키로 같은 호출을 재시도해도 두 번째 실행이 실행 대기열에 들어가지 않습니다. 대신 원본 핸들을 Idempotent-Replayed: true와 함께 반환합니다. 응답을 잃어버려 request_id를 놓칠 수 있는 상황이라면 직접 키를 전달하세요. 헤더를 참고하세요.
  • 결과는 만료됩니다. 완료된 요청은 완료 후 24시간 동안 보관됩니다. 그 이후에는 상태 및 결과 조회가 410을 응답하고 결과는 사라집니다. 신속하게 수집하고 출력에 담긴 에셋 URL을 다운로드하세요.
  • 폴링도 요청입니다. 상태 및 결과 조회는 호출자별 요청 비율에 포함됩니다. 짧은 고정 간격으로 폴링하기보다 Retry-After를 따르세요.

실행 대기열 오류 응답

모든 오류 응답에는 X-Comfy-Request-Id가 포함됩니다. 고객 지원 문의 시 이 값을 함께 알려주세요.

다음