Skip to main content
POST /v2/models/{provider}/{model}는 모델이 끝날 때까지 연결을 유지합니다. 대기 중 전달은 동일한 모델 ID와 동일한 네이티브 요청 본문을 사용하지만, Router가 실행을 수락하는 즉시 반환합니다. request_id를 곧바로 돌려받고, 결과가 준비되면 같은 프로세스에서든 다른 프로세스에서든 수집하면 됩니다. 생성이 유지할 수 있는 연결보다 오래 걸릴 수 있을 때, 웹 요청이 지금 반환되어야 할 때, 한 프로세스에서 제출하고 다른 프로세스에서 수집할 때, 또는 여러 생성을 동시에 진행하고 싶을 때 실행 대기열을 사용하세요. 순서, 수락, 재시도, 타임아웃, 과금 및 만료는 모두 서버에서 결정됩니다. 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 모두 요청을 지정하기 때문에 어디서나 두 ID가 필요합니다: 경로는 /v2/models/{provider}/{model}/requests/{request_id}입니다.

네 가지 라우트

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

Queue a request

This queues the same request the quickstart sends and collects the image. Export your key as COMFY_API_KEY first.
Every model page carries this shape for its own model under Queue and collect later, beside the synchronous snippet.

Follow progress and collect in one call

When you do want to wait but also want to show progress, subscribe folds submit, poll and collect into one call:
The timeout is a client-side bound with no server-side meaning. When it runs out, subscribe makes one best-effort cancel before raising. A cancel only takes effect on a request that has not started running: a generation already in flight at the partner completes and is charged whether or not anyone collects it. Use submit when the request should outlive the caller.

Collect from another process

Store the request_id next to the model ID. Both are needed to rebuild a handle, and no call is made until you use it.

Check status or cancel

status() is one poll and returns the current state. cancel() asks the server to stop a request that has not finished. It is a request, not a guarantee: a run already on the wire at the partner may complete anyway, and the next status() is what is true.

Async Python

AsyncComfy mirrors every name, argument and argument order. There is no submit_async, for the same reason there is no run_async.

Errors the SDKs raise

A request that finished without succeeding is reported as COMPLETED with an error_type. get() and subscribe() turn that into the typed Router error for the bucket: the classes in comfy_sdk.router_exceptions in Python, and routerErrors.* in TypeScript. The event iterator does not raise for that case, because it is a view of the queue’s progress: a completion carrying an error_type is yielded as the last observation, and get() is what collects. A 403 not_enabled on submit arrives as NotEnabled and is terminal, so the SDKs do not retry it.

응답 형태

제출, 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이 설정된 오류 응답으로 돌아오며, 동기 경로와 동일한 분류를 사용합니다. 취소. 202CANCELLATION_REQUESTED는 요청이 접수되었음을 의미할 뿐, 실행이 중단되었음을 뜻하지는 않습니다. 파트너 측에서 이미 전송 중인 실행은 그대로 완료될 수 있으며, 완료된 파트너 생성은 아무도 수집하지 않더라도 과금됩니다. 이후에 상태를 읽어 보세요. 취소가 적용된 경우 error_type: cancelled와 함께 COMPLETED로 표시됩니다. 실행되기 전에 만료된 요청은 같은 방식으로 queue_timeout을 표시합니다. 이미 완료된 요청은 ALREADY_COMPLETED와 함께 409로 응답합니다.

멱등성 및 과금

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

오류

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

다음

빠른 시작

동일한 모델을 위한 동기 호출로, 아무것도 없는 상태에서 이미지 한 장까지.

모델

모든 모델 페이지에는 해당 모델과 본문에 맞는 대기 중 요청 스니펫이 있습니다.

헤더

인증, 멱등성, 요청 ID, 오류 버킷, 재시도 간격.

API 레퍼런스

네 가지 실행 대기열 경로를 필드별로 설명합니다.