https://api.comfy.org
아래의 모든 엔드포인트에는 인증이 필요합니다. X-API-Key: <api-key> 또는 Authorization: Bearer <jwt>를 전송하십시오.
Comfy API 키는 Bearer 토큰으로도 전송할 수 있습니다. 두 자격 증명 헤더를 모두 제공하면 X-API-Key가 우선합니다. 키와 JWT의 구분은 인증 헤더를, 액세스 요구 사항은 퀵스타트를 참고하십시오.
엔드포인트
GET /v2/models
Comfy Router가 실행할 수 있는 모델을 나열합니다.
사용 가능한 모델 ID와 과금 정보를 나열합니다. has_more가 참인 동안 next_cursor를 사용하세요.
파라미터
RouterPageCursor
불투명 페이지네이션 커서입니다.Type:
RouterPageCursor — next_cursor로 반환되는 불투명 커서, 1–512자integer
한 페이지에 반환할 모델 수입니다.최대 100, 기본값: 20
RouterModelListResponse
OK - 모델 카탈로그의 한 페이지입니다.Body:
RouterModelListResponse — Headers: X-Comfy-Request-IdRouterErrorResponse
잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 이 요청이 허용되지 않습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdGET /v2/models/{provider}/{model}
정식 모델 ID로 파트너 모델 하나의 카탈로그 항목을 조회합니다.
전체 카탈로그를 나열하지 않고 모델 하나의 세부 정보를 조회합니다.
파라미터
RouterProviderSegment
필수
정식
{provider}/{model} 모델 ID의 공급자 부분입니다.유형: RouterProviderSegment. 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정식
{provider}/{model} 모델 ID의 모델 부분입니다.유형: RouterModelSegment. 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자RouterModelDetail
OK: 모델의 카탈로그 항목입니다.본문:
RouterModelDetail, 헤더: X-Comfy-Request-IdRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.본문:
RouterErrorResponse, 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.본문:
RouterErrorResponse, 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.본문:
RouterErrorResponse, 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.본문:
RouterErrorResponse, 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdPOST /v2/models/{provider}/{model}
정규 모델 ID로 파트너 모델을 동기식으로 실행합니다.
모델을 실행하고 완료된 결과를 같은 응답에서 받습니다.
파라미터
RouterProviderSegment
필수
정규
{provider}/{model} 모델 ID의 공급자 부분입니다.유형: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정규
{provider}/{model} 모델 ID의 모델 부분입니다.유형: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자string
하나의 논리적 호출을 다시 시도해도 안전하게 만드는 호출자 생성 키입니다.1–255자
string
이 모델을 현재 기본값 대신 다른 공급자가 제공하도록 선택합니다.
fal, wavespeed, runware, higgsfield가 대체 공급자이며, GET /v2/models/{provider}/{model}은 주어진 모델이 이 중 어떤 것을 지원하는지 보고합니다. 거부 사유는 고정된 순서로 검사되며, 앞선 사유는 뒤따르는 사유가 해당하든 하지 않든 응답합니다. 등록된 공급자가 전혀 아닌, 인식할 수 없는 값은 400으로 거부됩니다. 그다음, 본문이 멀티파트 작업(편집)을 선택하는 요청에서 대체 공급자는 detail이 “this request’s image selects the edit operation”으로 시작하는 409로 거부됩니다. 다만 해당 공급자의 이 모델용 변환기가 그 작업을 처리할 수 없을 때만 그렇습니다. 변환기가 미디어를 처리하는 경로는 정상적으로 진행됩니다. 그다음, 자체 키(BYOK) 자격 증명을 확인한 요청에서는 대체 공급자가 해당 공급자가 이 모델을 제공하는지와 무관하게 detail이 this request resolved a BYOK credential로 시작하는 409로 거부됩니다(해당 응답 참조). 그다음 지정된 공급자 자체의 게이트가 있는데, 이는 해당 공급자가 귀하에게 활성화되어 있지 않으면 error_type: not_enabled와 함께 403을, 게이트를 평가할 수 없으면 error_type: service_unavailable과 함께 503을 거부합니다. 그리고 이 네 가지를 모두 통과한 뒤에야 이 모델에 대한 경로가 없는 실제 공급자가 error_type: invalid_input과 함께 400으로 거부되며, 이는 인식할 수 없는 값과 같은 응답입니다. fallback_provider는 BYOK 요청에서, 본문이 멀티파트 작업을 선택하는 요청에서, 그리고 strict_mode=true인 경우에 거부되는 대신 아무 효과가 없습니다.boolean
model_provider와 함께일 때만 의미가 있습니다.기본값: Falsestring
첫 시도가 Router 또는 시도한 공급자에게 귀속되는 이유로 실패했을 때 Router가 이 호출을 모델의 다른 등록된 공급자에 대해 재시도할지 여부를 제어합니다. 생략하거나
false 이외의 값을 지정하면 폴백이 켜진 상태로 유지되고, false는 폴백을 끕니다. 성공한 폴백 응답에는 X-Comfy-Router-Fallback-Provider가 포함됩니다. BYOK 자격 증명을 확인한 요청에서는 이 파라미터가 무엇을 말하든 폴백을 사용할 수 없습니다. 시도가 아예 이루어지지 않고 첫 실패가 그대로 전달되며, 이는 거부가 아니라 아무 효과가 없는 것입니다. 여기서 409가 발생하지 않습니다. 같은 이유로, 본문이 멀티파트 작업을 선택하는 요청과 strict_mode=true인 경우에도 마찬가지입니다. 각각은 호출을 다른 공급자에 대해 충실히 재현할 수 없는 하나의 공급자에 묶기 때문에, 폴백은 거부되지 않고 단순히 건너뜁니다. 명시적인 model_provider만이 그 409로 거부되며, 이 무조건적 건너뜀과 달리 그 멀티파트 409는 변환기가 작업을 처리할 수 없는 경로에만 적용됩니다.boolean
이 모델의 입력 스키마가 선언하지 않은 최상위 요청 본문 필드를 수락하는 대신 거부하도록 선택합니다. 중첩 필드는 검사되지 않으며, 스키마가 선언되지 않은 필드를 허용하거나 작성된 스키마가 없는 모델에서는 아무것도 거부되지 않고,
strict_mode=true와 함께 전송된 대기 중 제출에서도 마찬가지입니다.기본값: Falseapplication/json — RouterModelInput (필수)
파트너 모델의 네이티브 JSON 입력입니다. model_provider가 없으면 요청은 모델의 기본 공급자에서 네이티브 디스패치를 실행하며, 이 본문은 모델 자체의 네이티브 스키마이고 변경 없이 전달됩니다(여기서 strict_mode는 의미가 없고 아무것도 바꾸지 않습니다). model_provider가 대체 공급자를 선택하고 strict_mode=false(기본값)인 경우, 본문은 전송되기 전에 해당 공급자의 실제 스키마로 변환됩니다. 정확히 표현할 수 없는 네이티브 필드는 삭제되고 응답의 X-Comfy-Router-Dropped-Params 헤더를 통해 공개되며, 결코 조용히 처리되지 않습니다. model_provider가 대체 공급자를 선택하고 strict_mode=true인 경우에는 변환이 실행되지 않습니다. 본문은 이미 이 모델의 네이티브 스키마가 아니라 해당 대체 공급자 자체의 실제 스키마여야 하며(strict_mode 참조), 변경 없이 전달됩니다. 본문 자체의 필드는 둘 이상의 작업을 지원하는 모델에서 Router가 어떤 작업을 실행할지도 선택합니다. 편집 가능한 이미지 모델의 경우 입력 이미지를 포함하면 텍스트 기반 이미지 생성에서 이미지 기반 이미지 생성(편집) 작업으로 전환되며, 이는 자체 요율로 과금될 수 있습니다. Seedance 비디오 모델의 경우 content[].role이 작업을 선택합니다(첫 프레임 이미지는 이미지 기반 비디오 생성, 레퍼런스 이미지나 클립은 레퍼런스 기반 비디오 생성). 네이티브 디스패치에서 Seedance 과금은 역할이 아니라 content의 미디어 종류를 따릅니다. 비디오 입력이 하나라도 있는 요청은 비디오 기반 비디오 생성으로, 그렇지 않고 이미지가 하나라도 있으면 이미지 기반 비디오 생성으로, 그 외에는 텍스트 기반 비디오 생성으로 과금됩니다. 다만 draft_task 항목에서 나온 최종 렌더는 그것이 렌더링하는 Draft의 작업으로 과금됩니다. 일부 모델은 텍스트 기반 비디오 생성과 이미지 기반 비디오 생성에 같은 요율을 부과합니다. model_provider가 대체 공급자를 선택하는 경우, 조건이 지정된 각 작업은 해당 공급자 자체의 요율로 과금될 수 있습니다.
응답
RouterModelOutput
정상 -
model_provider가 없거나, model_provider와 strict_mode=false(기본값, 가능하면 이 모델의 네이티브 계약으로 다시 변환되고, 변환에 실패하면 대체 공급자의 원시 응답으로 폴백합니다. 항상 로그에 기록되며 결코 조용히 넘어가지 않습니다)를 함께 보낸 경우 형태는 이 모델 자체의 네이티브 출력입니다. strict_mode=true인 경우에는 대체 공급자의 응답이 변경 없이 그대로 반환됩니다. 파트너가 생성 결과를 바이트로 직접 응답하는 모델의 경우, 본문은 application/json이 아니라 파트너 자체의 Content-Type을 따르는 해당 바이트입니다. 응답 Content-Type을 기준으로 분기하고 JSON 문서라고 가정하지 마세요.본문: RouterModelOutput 또는 원시 바이트(*/*) — 헤더: X-Comfy-Request-Id, X-Content-Type-Options, X-Comfy-Router-Fallback-Provider, X-Comfy-Router-Dropped-Params, X-Comfy-Credits-Used, Idempotent-Replayed, X-Committed-Spend-Limit, X-Committed-Spend-Current, X-Committed-Spend-RemainingRouterErrorResponse
잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, X-Comfy-Upstream-Status, X-Comfy-Upstream-Detail, X-Comfy-Refusal-Subject, Idempotent-ReplayedRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
X-Comfy-Error-Type을 확인하세요. concurrency_limit_exceeded는 원본 호출이 아직 실행 중이라는 뜻이므로 Retry-After를 기다린 뒤 같은 키를 재사용하세요. invalid_input은 새 키가 필요합니다. 이 라우트에서 발생하는 두 가지 invalid_input 충돌은 키와 전혀 관련이 없으며 새 키로도 어느 쪽도 해결되지 않습니다. model_provider가 대체 공급자를 지정하는 경우, 요청 본문이 해당 공급자의 이 모델용 translator가 처리할 수 없는 multipart 작업(편집)을 선택하면 거부되며, 그 detail은 “this request’s image selects the edit operation”으로 시작합니다. 그리고 그 이후에 확인되는 경우로, 요청이 경로에 있는 공급자에 대해 BYOK(bring-your-own-key) 자격 증명을 이미 확정한 경우이며, 그 detail은 this request resolved a BYOK credential로 시작합니다. model_provider를 제거하거나, BYOK 자격 증명 없이, 그리고 (multipart의 경우) 편집 없이 요청을 보내세요.본문: RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Retry-After(concurrency_limit_exceeded인 경우)RouterErrorResponse
요청 본문이 너무 큽니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterValidationErrorResponse
요청의 내용이 모델의 스키마에 대해 거부되었습니다.본문:
RouterValidationErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Idempotent-ReplayedRouterErrorResponse
X-Comfy-Error-Type을 확인하세요. concurrency_limit_exceeded는 진행 중인 호출을 줄이라는 뜻이고, rate_limited는 허용 창을 기다리라는 뜻입니다.본문: RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, X-Committed-Spend-Limit, X-Committed-Spend-Current, X-Committed-Spend-RemainingRouterErrorResponse
공급자 자체의 응답을 결과로 변환할 수 없습니다(
provider_error).본문: RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, X-Comfy-Upstream-StatusRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Retry-After(용량 거부인 경우에만)RouterErrorResponse
요청이 데드라인을 초과했습니다. 재시도하기 전에 오류 유형을 확인하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, X-Comfy-Upstream-Status, Retry-AfterPOST /v2/models/{provider}/{model}/estimate
실행하지 않고도 실행 전에 모델 호출의 가격을 산정합니다.
이 모델에서 이 본문을 실행할 때 Comfy가 청구할 금액을 미국 달러로 반환하며, 청구가 이루어지는 것과 동일한 요율표를 기준으로 가격이 산정됩니다. 본문은 먼저 모델의 입력 스키마에 대해 검증되며, 이는 기본 실행(strict_mode 없음, reject_unknown_fields 없음)이 검증하는 방식과 같습니다. 따라서 모델의 스키마를 통과하지 못하는 본문은 여기서도 실행 시와 동일한 422입니다. 공급자에게 아무것도 전달되지 않고 아무것도 청구되지 않습니다. 이 응답은 가격을 고정하는 것이 아닙니다. pricing_as_of 시점에 유효한 요율로 산정되며, 실행은 요율이 책정되는 시점에 유효한 요율로 청구됩니다. 기능이 순차 배포되는 동안 이 라우트는 error_type: not_enabled와 함께 403을 응답합니다.
파라미터
RouterProviderSegment
필수
정식
{provider}/{model} 모델 ID의 소문자 공급자 세그먼트로, 모델을 실행하는 파트너입니다.Type: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정식
{provider}/{model} 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다.Type: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자string
이 모델을 제공할 대체 공급자를 선택합니다. 현재의 기본 공급자 대신 사용됩니다.
application/json — RouterModelInput (필수)
파트너 모델의 네이티브 JSON 입력으로, 이 모델에 대해 동기 라우트가 받는 본문과 동일합니다. 기본 실행이 검증하는 방식대로 모델 자체의 입력 스키마에 대해 검증되며(이 라우트는 strict_mode나 reject_unknown_fields를 받지 않습니다), 본문 자체의 필드(출력 개수, 입력 이미지가 선택하는 작업)가 무엇의 가격을 산정할지 결정합니다.
응답
RouterCostEstimate
견적입니다.Body:
RouterCostEstimate — Headers: X-Comfy-Request-IdRouterErrorResponse
잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
요청 본문이 너무 큽니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterValidationErrorResponse
견적 요청의 본문이 모델의 스키마에 의해 거부되었거나, 경로에 지정된 것과 다른 모델을 지정했습니다.Body:
RouterValidationErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-Id, Retry-After (용량 거부에만 해당)GET /v2/models/{provider}/{model}/openapi.json
파트너 모델 하나의 입력 및 출력 스키마를 OpenAPI 문서로 읽어옵니다.
모델 하나의 입력 및 출력 스키마를 독립형 OpenAPI 문서로 읽어옵니다.
파라미터
RouterProviderSegment
필수
정규
{provider}/{model} 모델 ID의 공급자 부분입니다.유형: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정규
{provider}/{model} 모델 ID의 모델 부분입니다.유형: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자string
호출자가 이전
200 응답에서 보유한 ETag입니다.RouterModelInputSchemaDocument
OK - 모델의 입력 및 출력 스키마를 독립형 OpenAPI 문서로 반환합니다.본문:
RouterModelInputSchemaDocument — 헤더: X-Comfy-Request-Id, ETag, Cache-Controlno body
Not Modified - 호출자가
If-None-Match로 보낸 ETag 이후 문서가 변경되지 않았습니다.헤더: X-Comfy-Request-Id, ETag, Cache-ControlRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router가 요청을 완료할 수 없습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdPOST /v2/models/{provider}/{model}/requests
파트너 모델 실행을 실행 대기열에 제출하고 즉시 반환합니다.
Comfy Router의 대기 중 전달 모드입니다. 요청 본문은 POST /v2/models/{provider}/{model}가 이 모델에 대해 허용하는 것과 동일한 파트너 네이티브 JSON 입력입니다. 하나의 본문 형태, 모델별 스키마 하나, 두 가지 전달 모드가 있습니다. 다만 이 라우트는 결과를 위해 연결을 유지하지 않습니다. 실행을 접수하고 핸들과 함께 201로 응답하며, 호출자는 아래 세 가지 조회를 통해 나중에 결과를 수집합니다.
파라미터
RouterProviderSegment
필수
정규
{provider}/{model} 모델 ID의 소문자 공급자 세그먼트로, 모델을 실행할 대상 파트너입니다.유형: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정규
{provider}/{model} 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다.유형: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자string
현재 기본값 대신 이 모델을 제공할 대체 공급자를 선택합니다.
boolean
model_provider와 함께 사용할 때만 의미가 있습니다.기본값: Falsestring
호출자가 생성하는 키로, 하나의 논리적 호출을 안전하게 재시도할 수 있게 합니다.1–255자
boolean
이 모델의 입력 스키마가 선언하지 않은 최상위 요청 본문 필드를 수용하는 대신 거부하도록 선택합니다. 중첩 필드는 검사하지 않으며, 스키마가 선언되지 않은 필드를 허용하거나 작성된 스키마가 없는 모델의 경우, 또는
strict_mode=true로 전송된 대기 중 제출에서는 아무것도 거부되지 않습니다.기본값: Falseapplication/json — RouterModelInput (필수)
파트너 모델의 네이티브 JSON 입력으로, 이 모델에 대해 동기 라우트가 허용하는 본문과 동일하며, 작업을 선택하고 같은 방식으로 과금됩니다. 본문 자체의 필드가 둘 이상을 지원하는 모델에서 Router가 실행할 작업을 결정합니다(입력 이미지는 편집 가능한 이미지 모델을 이미지 기반 이미지 생성으로 전환하며, 이는 자체 요율로 과금될 수 있습니다. Seedance의 첫 프레임 이미지는 이미지 기반 비디오 생성을 선택하고, 레퍼런스 이미지나 클립은 레퍼런스 기반 비디오 생성을 선택합니다). 네이티브 디스패치에서 Seedance 요청은 역할이 아니라 content의 미디어 종류에 따라 과금됩니다. 비디오 입력이 있으면 비디오 기반 비디오 생성으로 과금되고, 그렇지 않고 이미지가 있으면 이미지 기반 비디오 생성으로, 그 외에는 텍스트 기반 비디오 생성으로 과금됩니다. 다만 draft_task 항목에서의 최종 렌더는 그것이 렌더링하는 Draft의 작업으로 과금되며, 일부 모델은 텍스트 기반 비디오 생성과 이미지 기반 비디오 생성에 동일한 요율을 부과합니다. model_provider로 대체 공급자를 선택하면 각 조건화된 작업은 해당 공급자 자체의 요율로 과금될 수 있습니다. 디스패치 시에도 동일한 공급자 선택 계약이 적용됩니다. model_provider가 없거나, model_provider가 있고 strict_mode=false(기본값)인 경우 본문은 모델의 네이티브 문서이며 실행이 접수되기 이전에 모델 자체의 입력 스키마에 대해 검증되므로, 모델이 거부할 본문은 몇 분 후 실패하는 대기 중 요청이 아니라 여기서 422가 됩니다. 비엄격 대체 공급자 본문은 디스패치 시 해당 공급자의 실제 스키마로 추가로 변환됩니다. strict_mode=true인 경우 본문은 이미 대체 공급자 자체의 스키마여야 하며 변경 없이 전달됩니다. 네이티브 스키마 검증은 동기 라우트에서와 정확히 마찬가지로 건너뜁니다(model_provider와 strict_mode 참조).
응답
RouterQueueSubmitResponse
생성됨 - 실행이 실행 대기열에 접수되었습니다.본문:
RouterQueueSubmitResponse — 헤더: X-Comfy-Request-Id, Idempotent-ReplayedRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
요청 본문이 너무 큽니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자나 모델에 대해 요청이 허용되지 않습니다. 파트너가 생성을 바이트로 직접 응답하는 모델은 아직 실행 대기열에 넣을 수 없으며
not_enabled로 거부됩니다. 대신 동기 라우트에서 실행하세요.본문: RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
X-Comfy-Error-Type을 확인하세요: concurrency_limit_exceeded는 원본 호출이 아직 실행 중이라는 뜻이므로, Retry-After만큼 기다린 뒤 동일한 키를 재사용하세요. invalid_input은 새 키가 필요합니다. 이 라우트에서 발생하는 두 가지 invalid_input 충돌은 키와 전혀 관련이 없으며, 어떤 새 키로도 해결되지 않습니다: model_provider가 대체 공급자를 지정하는 경우, 요청 본문이 해당 공급자의 이 모델용 변환기가 처리할 수 없는 멀티파트 작업(편집)을 선택하면 거부되며, 그 detail은 “this request’s image selects the edit operation”로 시작합니다. 그리고 그 이후에 검사되는 경우로, 요청이 경로에 있는 공급자에 대해 이미 BYOK 자격 증명을 확인한 상태라면 거부되며, detail은 this request resolved a BYOK credential로 시작합니다. model_provider를 제거하거나, BYOK 자격 증명 없이 (멀티파트의 경우에는 편집도 없이) 요청을 보내세요.본문: RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Retry-After (concurrency_limit_exceeded인 경우)RouterValidationErrorResponse
요청 내용이 모델의 스키마와 일치하지 않아 거부되었습니다.본문:
RouterValidationErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Idempotent-ReplayedRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Retry-After (용량 거부에만 해당)GET /v2/models/{provider}/{model}/requests/{request_id}
제출된 요청 하나의 결과를 수집합니다.
수집 엔드포인트입니다. 성공적으로 완료된 요청에 대해서는 파트너 모델 자체의 네이티브 출력을 반환합니다. 이는 동일한 모델과 동일한 입력에 대해 동기 라우트의 200이 담는 것과 바이트 단위로 동일합니다. 따라서 두 전달 방식은 하나의 결과 형태를 만들어내며, 호출자는 두 번째 파서 없이 두 방식 사이를 오갈 수 있습니다.
파라미터
RouterProviderSegment
필수
정규
{provider}/{model} 모델 ID의 소문자 공급자 세그먼트입니다. 모델이 실행되는 파트너입니다.유형: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정규
{provider}/{model} 모델 ID의 소문자 모델 세그먼트입니다. 해당 공급자 내에서 실행할 모델입니다.유형: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자RouterQueueRequestId
필수
대상으로 삼을 대기 중 요청입니다. 제출 시 본문에서 반환된
request_id입니다.유형: RouterQueueRequestId — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자RouterModelOutput
OK - 결과를 생성한 요청, 즉 성공적으로 완료된 요청이거나 기록된 과금과 저장된 결과를 모두 가진 터미널 요청에 대해 저장된 결과입니다. 파트너 자체의 미디어 타입으로 변경 없이 반환되며, 동기 라우트의
200이 반환하는 방식과 정확히 동일하고, 제출이 수락한 것과 동일한 공급자 선택 계약을 따릅니다. model_provider 없이, 또는 model_provider와 함께 strict_mode=false(기본값, 가능한 경우 이 모델의 네이티브 계약으로 다시 변환되며, 변환에 실패하면 대체 공급자 자체의 원시 응답으로 폴백합니다. 이는 기록되며 결코 조용히 넘어가지 않습니다)인 경우 형태는 이 모델 자체의 네이티브 출력입니다. strict_mode=true이면 대체 공급자의 응답이 변경 없이 반환됩니다. 파트너가 생성 결과를 바이트로 직접 응답하는 모델의 경우, 본문은 application/json이 아니라 파트너 자체의 Content-Type 아래에 있는 해당 바이트입니다. 응답 Content-Type을 기준으로 분기하고 JSON 문서라고 가정하지 마십시오.본문: RouterModelOutput 또는 원시 바이트(*/*) — 헤더: X-Comfy-Request-Id, X-Content-Type-OptionsRouterQueueStatusResponse
Accepted - 요청이 아직 완료되지 않았습니다.본문:
RouterQueueStatusResponse — 헤더: X-Comfy-Request-Id, Retry-AfterRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해 요청이 허용되지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하십시오.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
요청이 작업과 충돌하는 상태입니다. 오류 유형을 확인하십시오.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
요청이 데드라인을 초과했습니다. 재시도하기 전에 오류 유형을 확인하십시오.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterValidationErrorResponse
요청의 내용이 모델의 스키마에 대해 거부되었습니다.본문:
RouterValidationErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id, Idempotent-ReplayedRouterErrorResponse
Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdPUT /v2/models/{provider}/{model}/requests/{request_id}/cancel
제출된 요청 하나에 대해 취소를 요청합니다.
아직 끝나지 않은 요청을 중지하도록 Comfy에 요청합니다. 이는 요청일 뿐 보장이 아니며, 202는 바로 그 점을 나타냅니다. CANCELLATION_REQUESTED는 요청이 접수되었다는 뜻이지 실행이 중지되었다는 뜻이 아닙니다. 파트너에서 이미 전송 중인 실행은 그대로 완료될 수 있으며, 완료된 파트너 생성은 누군가 결과를 수집했는지와 무관하게 과금됩니다. 따라서 실제로 무슨 일이 일어났는지 알아야 하는 호출자는 이후 상태 엔드포인트를 조회해야 합니다. 이때 실제로 적용된 취소는 다른 모든 최종 결과와 마찬가지로 error_type을 함께 지닌 COMPLETED로 나타납니다.
파라미터
RouterProviderSegment
필수
정규
{provider}/{model} 모델 ID의 소문자 공급자 세그먼트로, 실행되는 모델의 파트너입니다.Type: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정규
{provider}/{model} 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다.Type: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자RouterQueueRequestId
필수
처리할 대기 중 요청으로, 제출 시 본문에서 반환된
request_id입니다.Type: RouterQueueRequestId — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자RouterQueueCancelResponse
수락됨 -
CANCELLATION_REQUESTED.Body: RouterQueueCancelResponse — Headers: X-Comfy-Request-IdRouterQueueCancelResponse
충돌 -
ALREADY_COMPLETED.Body: RouterQueueCancelResponse — Headers: X-Comfy-Request-IdRouterErrorResponse
잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 해당 요청이 허용되지 않습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router 요청 수준의 실패로, 요청이 모델에 도달하지 않았거나 모델 자체가 보고하지 않은 이유로 실패한 경우입니다.Body:
RouterErrorResponse — Headers: X-Comfy-Error-Type, X-Comfy-Request-IdGET /v2/models/{provider}/{model}/requests/{request_id}/status
제출된 요청 하나의 실행 대기열 상태를 조회합니다.
폴링 엔드포인트입니다. 요청의 현재 상태만 응답하며 결과는 반환하지 않습니다. 따라서 클라이언트는 매 폴링마다 출력을 전송받지 않고도 오래 걸리는 생성 작업을 지켜볼 수 있습니다. 결과는 이 응답이 COMPLETED를 나타낼 때 아래의 조회를 통해 한 번만 수집합니다.
파라미터
RouterProviderSegment
필수
정식
{provider}/{model} 모델 ID의 소문자 공급자 세그먼트입니다. 모델을 실행하는 파트너입니다.유형: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정식
{provider}/{model} 모델 ID의 소문자 모델 세그먼트입니다. 해당 공급자 내에서 실행할 모델입니다.유형: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자RouterQueueRequestId
필수
처리할 대기 중 요청입니다. 제출 시 본문에서 반환된
request_id입니다.유형: RouterQueueRequestId — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자RouterQueueStatusResponse
OK - 요청의 현재 실행 대기열 상태입니다.본문:
RouterQueueStatusResponse — 헤더: X-Comfy-Request-Id, Retry-AfterRouterErrorResponse
자격 증명이 누락되었거나 유효하지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
모델 ID를 찾을 수 없습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-IdRouterErrorResponse
Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.본문:
RouterErrorResponse — 헤더: X-Comfy-Error-Type, X-Comfy-Request-Id오류 버킷
기계가 읽을 수 있는 Router 오류 카테고리이며,X-Comfy-Error-Type 헤더로도 전송됩니다.
요청 수준 버킷
Router가 요청을 접수한 뒤 완료하지 못한 경우 발생합니다.전송 수준 버킷
모델 호출 이전이나 그 무렵에 Router 자체에서 발생합니다.응답 헤더
string
제공되는 스키마 문서에 대한 신선도 지시문입니다.
string
GET /v2/models/{provider}/{model}/openapi.json에 대해 제공되는 문서 바이트에 대한 강력한 엔티티 태그입니다.boolean
모델을 다시 실행한 것이 아니라
Idempotency-Key의 기록에서 이 응답이 제공된 경우 존재하며 true입니다.integer
변경 없이 동일한 요청을 다시 보내기 전에 기다릴 초입니다.전송 시:
503integer
대기 중인 요청을 다음에 폴링하기 전에 기다릴 초입니다.전송 시:
200, 202integer
동일한
Idempotency-Key로 동일한 요청을 재시도하기 전에 기다릴 초입니다.전송 시: 409, 504string
이 실행에 든 비용을 Comfy 크레딧으로 나타낸 것으로, 청구 자체가 기준으로 삼는 것과 동일한 요금표에서 산정됩니다. 따라서 호출자는 자체 가격표가 필요 없으며, 유료 호출을 두 번 이상 거쳐 공급자에 도달한 실행에서는 마지막 호출의 값이 아니라 그 합계입니다.
RouterErrorType
실패에 대한 대략적인 기계 판독 가능 버킷으로, Router가 모든 오류 응답에 설정합니다.타입:
RouterErrorTypestring
콘텐츠 정책 거부가 입력 또는 출력 중 어느 쪽에 관한 것인지 나타내는 Router 수준의 폐쇄형 어휘입니다:
input, output, input_text, input_image, input_video, input_audio, output_text, output_image, output_video, output_audio.string
이 호출에 대해 서버가 생성한 식별자로, 모든 Router 응답에 존재합니다. 성공, 4xx, 5xx 모두 마찬가지입니다. 오류 응답이야말로 사용자가 지원 요청에 인용할 id가 필요한 바로 그 순간이기 때문입니다.
string
문자열 배열을 담은 하나의 JSON 인코딩 문자열입니다. 쉼표로 분리하지 말고 JSON 파서로 디코딩하세요. 전송되는 값은 쉼표로 구분된 OpenAPI 배열이 아니라 단일 문자열이며, 각 항목은 그 자체로 쉼표를 포함하는 문장이기 때문입니다. 이 호출의 요청 본문을 변환한 결과 해당 공급자에서 하나 이상의 네이티브 필드를 정확히 표현할 수 없었을 때마다 존재하며, 누락된 각 필드와 그 이유를 명시합니다. 호출자가
model_provider로 해당 변환을 요청했든(strict_mode=false, 기본값) 자동 fallback_provider 재시도가 실행되었든 마찬가지입니다.string
fallback_provider가 실제로 이 호출을 두 번째 공급자에 대해 재시도했고 그 재시도가 성공한 경우에만 공급자 이름과 함께 존재합니다. 최종적으로 이 호출을 처리한 공급자이며, 시도되었다가 역시 실패한 공급자는 결코 아닙니다.string
모델 공급자가 요청을 거부한 이유를 길이를 제한하고 정제하여 제시한 것입니다.
integer
이 호출에 대한 모델 공급자 자체의 HTTP 상태입니다.
integer
호출자가 현재 진행 중인 호출에 확정한 미국 달러 센트 금액입니다.
integer
호출자가 진행 중인 호출에 확정할 수 있는 파트너 지출의 상한(미국 달러 센트)입니다. 호출이 승인되는 순간부터 금액이 보류되고 해당 호출이 끝나면 해제됩니다.
integer
상한 아래에 남은 여유분(미국 달러 센트)으로, 최소 0입니다.
string
Router 모델의 모든 성공 실행에서 항상
nosniff입니다.실행 전 비용 추정
POST /v2/models/{provider}/{model}/estimate는 본문을 실행하지 않고 가격을 산정하며, 대기 중 제출(POST /v2/models/{provider}/{model}/requests)은 201 응답에서 estimate와 동일한 RouterCostEstimate를 반환합니다. 둘 다 Comfy가 해당 실행에 청구하는 요율 카드를 기준으로 가격이 산정됩니다. 자체 공급자 키로 실행한 경우에는 Comfy가 청구하지 않습니다(아래 참조). 추정 기능이 점진적으로 배포되는 동안에는 이 경로가 error_type: not_enabled와 함께 403을 응답하고, 제출 응답에서는 estimate가 생략됩니다. 카탈로그에는 여전히 가격이 없습니다.
어떤 금액보다도 source를 먼저 확인하세요. 수치가 누락되었다고 해서 무료라는 뜻은 결코 아닙니다.
unknown 추정의 reason은 다음 중 하나입니다.
not_quotable: Router가 실행 전에 이 호출의 가격을 산정할 수 없습니다. 본문이 범위를 정하지 않은, 공급자가 나중에 보고하는 수량을 기준으로 청구되거나, 본문을 전송된 그대로 가격 산정할 수 없기 때문입니다. 인식되지 않는reason은 모두not_quotable로 취급하세요.unpriced_model: 요율 카드에 이 요청의 가격이 없습니다.byok(대기 중 제출 전용): 자체 공급자 키로 실행하므로 Comfy는 이에 대해 아무것도 청구하지 않습니다.pricing_unavailable(대기 중 제출 전용): 요청이 접수될 때 요율 카드를 읽을 수 없었습니다. 제출은 그대로 수락되며 실행은 평소와 같이 청구됩니다.
- 수치를 내려면 요율 카드가 필요한데 카드가 로드되지 않았거나 오래된 경우,
/estimate는 추측 대신503을 응답합니다. 대기 중 제출은 추정 때문에 거부되는 일이 없으며, 대신reason: pricing_unavailable과 함께source: unknown을 포함합니다. 실행 전에 전혀 가격을 산정할 수 없는 호출(not_quotable)이나 자체 공급자 키를 사용하는 대기 중 제출(byok)은 카드를 읽지 않고 응답하므로, 그200은 카드가 최신인지에 대해 아무것도 말해주지 않습니다. /estimate는 기본 실행과 마찬가지로 모델 자체의 입력 스키마에 대해 본문을 검증하므로, 모델 스키마를 통과하지 못하는 본문은 실행이 응답했을 것과 동일한detail[]형태의 동일한422를 받습니다. 가격 산정도 디스패치도 이루어지지 않습니다.- 대기 중 제출의 멱등 재실행(
Idempotent-Replayed: true)은 원본 견적이 저장되지 않으므로estimate를 생략합니다.
200 수치가 실행이 수락된다거나 정확히 그 금액이 청구된다는 약속은 아닙니다.
/estimate는strict_mode나reject_unknown_fields를 받지 않으므로 모델의 네이티브 계약만 검사합니다.strict_mode=true실행이 대체 공급자 자체 스키마에서 수락하는 본문이 여기서는422를 받을 수 있고,reject_unknown_fields=true실행이라면 거부했을 선언되지 않은 최상위 필드도 여기서는 가격이 산정됩니다.pricing_as_of는 요율 카드를 가져온 시점입니다(카드를 읽지 않은 경우에는 추정이 응답된 시점). 이는 가격 고정이 아닙니다. 실행은 요율이 적용되는 시점에 유효한 요율로 청구됩니다./estimate는model_provider가 지정한 레그, 또는 네이티브 공급자의 가격을 제시합니다.fallback_provider나strict_mode매개변수는 받지 않습니다. 폴백 재시도가 다른 공급자로 넘어간 동기 실행은 그 공급자의 요율로 청구되며, 추정은 이를 제시하지 않았습니다. 실행 응답의X-Comfy-Router-Fallback-Provider가 그런 일이 있었음을 알려줍니다. 대기 중 제출에는 폴백이 없으므로 그estimate는 실제로 실행되는 레그의 가격을 제시합니다./estimate와 대기 중 제출의estimate는model_provider레그에서 동일한 본문에 대해, 또는 형제 작업에서 실행되는 본문에 대해 약간 다른 문서의 가격을 산정할 수 있습니다. 제출의estimate는 실행이 전송하는 문서를 기준으로 가격이 산정됩니다./estimate는 항상 플랫폼 요금을 제시합니다. 자체 공급자 키로 실행한 경우 Comfy는 청구하지 않지만,/estimate는 이를 감지하지 못하고 여전히 수치를 반환합니다.reason: byok를 응답하는 것은 대기 중 제출뿐입니다.- 달러는 반올림되지 않은 센트에서 최대 소수점 8자리로 표시되며, 청구 가능한 1센트 미만의
amount가0으로 표시되는 일은 없습니다.credits는round(amount × 211, 2)로,X-Comfy-Credits-Used가 요금에 적용하는 것과 동일한 변환입니다. 따라서 0이 아닌 아주 작은 가격에서credits가0으로 반올림될 수 있습니다. 이것이 중요한 경우에는credits가 아니라amount또는amount_cents를 기준으로 예산을 세우세요. 해당 헤더는 실행에 대한 사후 수치로 남으며, 잔액은 Comfy 플랫폼에 있습니다.
결과 에셋
모델은 에셋 URL, 인라인 바이트, 또는 둘 다를 반환할 수 있습니다. 아래 공급자는 선택된 에셋을 Comfy 스토리지로 복사하고 해당 URL을 대체합니다. 이 동작은 모델에 따라 다르며, 이를 선택하는 요청 헤더는 없습니다.
이 수명은 URL에 서명될 때 시작되며, URL을 열 때 시작되는 것이 아닙니다. 캐시되었거나 재생된 URL은 남은 시간이 더 적을 수 있으며, 재생해도 수명이 갱신되지 않습니다. 에셋을 즉시 다운로드하세요. 각 행에 명시된 에셋만 복사됩니다.
byteplus/seedream-* 및 byteplus/seededit-* 이미지는 BytePlus 비디오 행에 포함되지 않습니다.
복사는 해당 모델의 네이티브 공급자만 수행합니다. 대체 공급자가 처리한 실행, 즉 model_provider가 대체 공급자를 지정한 경우나 폴백 재시도가 대체 공급자에 도달한 네이티브 실행(X-Comfy-Router-Fallback-Provider로 공개됨)은 해당 공급자 자체의 URL을 반환하며, 이 URL은 공급자의 만료 정책을 따르고 복사되지 않습니다. model_provider 값 default, comfy, comfyui는 대체 공급자를 지정하지 않으므로 해당 실행은 네이티브이며 위와 같이 복사됩니다. 폴백 재시도가 다시 네이티브 공급자에 도달한 model_provider 실행도 마찬가지입니다.
Veo(veo/*)는 별도의 스토리지 경로를 사용합니다. response.videos[]에서 존재하는 멤버를 읽으세요. bytesBase64Encoded는 클립을 인라인으로 담고 있으며, gcsUri는 환경이 공급자의 Comfy 스토리지 직접 쓰기에 맞게 구성된 경우 Comfy가 서명한 HTTPS 링크를 담고 있습니다. 해당 링크는 응답 시점부터 24시간 동안 유효합니다. 후자의 경우 에셋을 복사하는 대신 직접 쓰기 때문에 Veo는 재호스팅 표에 포함되지 않습니다.
다른 모델은 공급자 에셋 참조 또는 인라인 바이트를 반환합니다. 공급자 URL은 공급자의 만료 정책을 따르며, 이는 위 수명보다 훨씬 짧을 수 있고 Router 계약에 명시되어 있지 않습니다.
복사는 에셋별 최선 노력 방식으로 수행됩니다. 복사 하나가 실패하면 해당 항목은 공급자 참조를 유지합니다. 응답에는 Comfy URL과 공급자 URL이 모두 포함될 수 있으며, 에셋별 복사 상태 필드는 명시적으로 없습니다. 생성은 여전히 성공하며 과금됩니다. 성공적으로 재호스팅된 에셋 하나로 모든 URL의 수명을 추론하지 마세요.
결과가 Comfy 호스팅인지 여부는 완료된 호출을 나중에 해당 Idempotency-Key 레코드에서 재생할 수 있는지도 결정합니다. 위의 Idempotency-Key 매개변수는 재생할 수 없을 때 재시도에 무엇이 응답되는지 설명합니다.
모델별 입력 및 출력 스키마
각 모델의 필드는GET /v2/models/{provider}/{model}/openapi.json에서 확인할 수 있습니다. 이 호출에는 API 키가 필요합니다. 스키마가 작성된 모든 모델에 대해 동일한 문서가 이 사이트에도 인증 없이 /router-schemas/{provider}/{model}.json에서 게시됩니다. 이 복사본은 마지막 문서 업데이트 시점에 캡처한 스냅샷이므로, 두 문서가 다를 경우 엔드포인트가 우선합니다. 오퍼레이션의 requestBody는 입력 검증을 설명하고, 200 응답은 스키마가 작성된 경우 출력 형태와 미디어 타입을 설명합니다. x-comfy-input-schema-authored가 false이면 Router는 모델별 사전 검증 없이 모든 JSON 객체를 허용합니다. 공급자 요구 사항은 여전히 적용됩니다. 출력 스키마는 결과를 설명하며, Router는 반환된 공급자 페이로드를 스키마와 대조하여 검증하지 않습니다. 스키마가 작성되지 않은 출력은 application/json 대신 */*를 사용할 수 있으므로, 디코딩하기 전에 응답 콘텐츠 타입을 확인하세요.
스키마
RouterChargesOnPolicyRejection
이 모델에 대해 콘텐츠 정책 거부가 청구되는지 여부입니다. 알 수 없는 값은 청구될 수 있는 것으로 간주하세요. 유형:string
RouterCostEstimate
이 호출에 대해 Comfy가 청구할 금액으로, 디스패치 이전에 청구가 과금되는 것과 동일한 요율표를 기준으로 산정되며 미국 달러로 표시됩니다.source는 이 숫자를 얼마나 신뢰할 수 있는지 나타냅니다. exact는 amount를 포함하고, estimated는 min_amount와 max_amount를 포함하며 amount는 없고, unknown은 둘 다 없이 reason을 포함합니다. 누락된 amount를 무료로 해석하지 마세요. 가격 고정이 아닙니다. pricing_as_of를 참고하세요.
필드
string
필수
exact | estimated | unknown; 그 외의 값은 unknown으로 해석합니다.string
필수
항상
USD입니다.string
달러를 소수점 문자열로 나타낸 값입니다. 예: “0.04”. 소수점 이하 최대 8자리이며 지수 표기를 쓰지 않습니다. 청구 대상이 되는 1센트 미만 가격은 “0”으로 표시되지 않습니다.
source가 exact일 때만 존재합니다.string
달러 기준 하한값을 소수점 문자열로 나타낸 값입니다.
source가 estimated일 때만 존재합니다.string
달러 기준 상한값을 소수점 문자열로 나타낸 값입니다.
source가 estimated일 때만 존재합니다.number
산술 연산에 쓰기 위해 같은 값을 반올림하지 않은 미국 센트 단위로 나타낸 값입니다.
amount와 함께 존재합니다.doublenumber
반올림하지 않은 미국 센트 단위의
min_amount입니다. min_amount와 함께 존재합니다.doublenumber
미국 센트 단위의
max_amount입니다. max_amount와 함께 존재합니다.doublenumber
플랫폼 환산율($1 = 211 크레딧)을 사용해
amount를 Comfy 크레딧으로 나타낸 값이며 소수점 이하 2자리로 반올림됩니다. exact 견적에 대해 X-Comfy-Credits-Used가 담게 될 값입니다.doublestring
필수
이 견적이 대상으로 하는 공급자 구간입니다. 대기 중 제출에서는 실행될 구간입니다.
RouterModelId
필수
정식 Comfy Router 모델 ID인
{provider}/{model}이며, POST /v2/models/{provider}/{model}에서 모델을 지정하는 값과 정확히 같습니다. 따라서 호출자는 다른 것에서 다시 도출할 필요 없이 이 값을 그 경로에 그대로 넣을 수 있습니다. 이 값의 pattern은 RouterProviderSegment와 RouterModelSegment를 단일 /로 연결한 것이고, maxLength는 두 값의 길이 합에 그 구분자를 더한 값입니다.Type: RouterModelId — 모델 ID, 예: anthropic/claude-opus-4-6, 최대 193자string
필수
이 견적을 산정할 때 사용한 요율표를 가져온 시각입니다. 실행은 이 시점이 아니라 요금이 산정되는 시점에 유효한 요율로 청구됩니다. 요율표를 읽지 않은 경우(
reason: pricing_unavailable, byok, 또는 어떤 요율표로도 산정할 수 없는 not_quotable 호출)에는 이 값이 견적이 응답된 시각입니다.date-timestring
source가 unknown일 때만 존재합니다. not_quotable(Router가 실행 전에 이 호출의 가격을 산정할 수 없음. 가격이 공급자가 보고하는 내용에 따라 달라지거나, 요청 본문이 청구 대상 수량을 한정하지 않는 경우), unpriced_model(요율표에 이 요청의 가격이 없음), byok(대기 중 제출에만 해당: 실행에 사용자의 공급자 키를 사용하므로 Comfy는 이에 대해 아무것도 청구하지 않음), 또는 pricing_unavailable(대기 중 제출에만 해당: 요청이 접수될 때 요율표를 읽을 수 없었음. 이는 일시적이며 실행은 평소와 같이 청구됨)입니다. 그 외의 값은 not_quotable로 해석합니다.RouterErrorResponse
인증, 접근, 모델 조회, 할당량 및 공급자 전송 실패에 대한 오류 본문입니다. 필드string
필수
사람이 읽을 수 있는 실패 설명이며, 최종 사용자에게 그대로 보여줘도 안전합니다. 기계적으로 파싱되지 않으므로 대신
error_type을 기준으로 분기하세요. 지원이 종료된 모델에 대한 model_not_found의 경우, 후속 모델이 기록되어 있고 호출자에게 표시된다면 detail은 <id> was retired on <YYYY-MM-DD>; use <successor>로 표시되고, 그렇지 않다면 일반적인 제안 목록 대신 <id> was retired on <YYYY-MM-DD>만 표시됩니다. 여기에 명시된 후속 모델은 항상 호출을 다시 지정할 수 있는 실제 카탈로그 ID입니다. 지원 종료 날짜가 아직 미래인 모델은 지원이 종료된 것이 아닙니다. 해당 날짜까지 GET /v2/models에 계속 나열되며 계속 실행할 수 있습니다. detail의 나머지 부분과 마찬가지로, 이 지원 종료 관련 문구는 표시용이며 호환성 보장이 없습니다. 기계적으로 파싱되지 않는다는 규칙에 대한 문서화된 두 가지 예외가 있습니다. POST /v2/models/{provider}/{model}에서 409는 invalid_input 버킷을 공유하는 서로 무관한 세 가지 조건에 대해 응답되며, 이들을 구분하는 것은 오직 detail뿐입니다. “this request’s image selects the edit operation”으로 시작하는 detail은 multipart model_provider 거부이고, this request resolved a BYOK credential로 시작하는 detail은 BYOK model_provider 거부입니다. 어느 쪽도 새 Idempotency-Key로 해소되지 않습니다. 해당 경로에서 그 외의 invalid_input 409는 키 충돌입니다. 두 접두사는 모두 안정적인 계약 용어이며 매칭에 사용할 수 있습니다. 그 외 다른 곳에서는 detail을 기준으로 분기하는 것이 호환성 보장을 가지지 않습니다.RouterErrorType
필수
Router 실패에 대한 거칠게 분류된 기계 판독 가능 버킷으로, 호출자가 본문을 파싱하지 않고 분기할 수 있도록
X-Comfy-Error-Type 응답 헤더에 반영됩니다. 이 집합은 열아홉 개 값으로 닫혀 있습니다. 여섯 개의 요청 수준 버킷 invalid_input, content_policy_violation, provider_error, provider_timeout, insufficient_credits, model_not_found와 전송 수준의 unauthorized, forbidden, concurrency_limit_exceeded, client_disconnected, internal_error, deadline_exceeded, not_enabled, service_unavailable, rate_limited, cancelled, queue_timeout, request_not_found, queue_backlog_full입니다. 닫혀 있다는 것은 오늘 문서화된 대로의 집합을 설명하는 것이지 영원히 유지되는 한계가 아닙니다. 집합은 늘어날 것으로 예상되며, 그래서 이것은 의도적으로 enum이 아닌 일반 문자열입니다. 따라서 클라이언트는 위 목록을 전수 switch하여 다음 추가에서 깨지는 대신, 인식할 수 없는 값을 internal_error로 처리해야 합니다.Type: RouterErrorTypestring
모델 공급자가 요청을 거부한 이유에 대해 정리되고 정제된 설명으로,
error_type이 invalid_input이고 X-Comfy-Upstream-Status가 공급자의 4xx 또는 2xx일 때만 존재합니다. 즉, 공급자가 요청을 형식 오류로 거부하면서 그 이유를 밝힌 경우입니다. 보통 이 상태는 4xx이며, 거부된 생성을 성공 응답 봉투 안에 담아 보고하는 공급자의 경우 2xx입니다 (BytePlus의 실패한 작업 폴링은 HTTP 200이고 이유가 본문에 담겨 있습니다). 공급자 5xx, 전송 실패, 콘텐츠 정책 거부, 그리고 Router가 스스로 제기한 모든 거부를 포함한 다른 모든 실패에서는 존재하지 않습니다. 이는 X-Comfy-Upstream-Detail 헤더를 반영합니다.string
콘텐츠 정책 거부가 어떤 입력 또는 출력에 관한 것이었는지를 Router 수준의 닫힌 어휘로 나타냅니다.
input, output, input_text, input_image, input_video, input_audio, output_text, output_image, output_video, output_audio. 공급자가 모달리티를 명시하지 않은 경우에는 접두사 없는 input / output 값이 어느 쪽인지를 나타냅니다. error_type이 content_policy_violation이고 공급자가 거부된 대상을 기계 판독 가능한 코드로 명시한 경우에만 존재하며, 그렇지 않으면 없습니다. 공급자 텍스트는 절대 아닙니다. 현재 BytePlus, Runway, BFL, Gemini, Veo, Vertex, xAI, Wan의 거부에 대해 명시되며, 거부가 어느 쪽에 관한 것인지 밝히지 않는 공급자의 경우 이 필드는 없습니다. 이는 X-Comfy-Refusal-Subject 헤더를 반영합니다.RouterErrorType
기계가 읽을 수 있는 Router 오류 카테고리로,X-Comfy-Error-Type 헤더에도 전송됩니다.
유형: string
RouterModelBilling
모델을 호출하기 전에 확인해야 하는 과금 동작입니다. 가격이나 사용량은 포함하지 않습니다. 필드RouterChargesOnPolicyRejection
필수
이 모델이 콘텐츠 정책을 이유로 거부한 호출이 그럼에도 호출자에게 과금되는지 여부입니다. 공급자마다 다르고, 그 차이는 호출 시점에는 보이지 않으며, 같은 호출에 대해 오류와 과금을 함께 보게 된 사용자는 미리 알 방법이 없었습니다. 그래서 공급자마다의 통설에 맡기는 대신, 모델별로 호출 전에 명시합니다.타입:
RouterChargesOnPolicyRejectionRouterModelDetail
하나의 Comfy Router 모델에 대한 모델별 상세 정보입니다. 카탈로그 목록이 해당 모델에 대해 보고하는 모든 항목에 더해, 단일 모델 라우트만 제공하는 모델별 필드까지 포함합니다.RouterModelListEntry, RouterModelDetailFields로 구성됩니다.
타입: object
RouterModelDetailFields
모델 세부 정보 엔드포인트가 반환하는 선택적 필드입니다. 필드string
이 모델의 OpenAPI 문서 URL이며, 입력 및 출력 스키마를 포함합니다.HTTPS URL, 예:
https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json, 최대 2048자RouterModelId
POST /v2/models/{provider}/{model}에 사용되는 모델 ID입니다.
타입: string, 모델 ID, 예: anthropic/claude-opus-4-6, 최대 193자
RouterModelInput
모델 입력 객체입니다. 필드와 검증 정보는 선택한 모델의 OpenAPI 문서를 참고하세요. 타입:object
RouterModelInputSchemaDocument
한 모델의 입력과 출력을 위한 독립형 OpenAPI 문서입니다. 타입:object
RouterModelListEntry
모델의 ID와 청구 정보. 필드RouterModelId
필수
정식 Comfy Router 모델 ID인
{provider}/{model}로, POST /v2/models/{provider}/{model}에서 모델을 지정하는 값과 정확히 동일합니다. 따라서 호출자는 다른 곳에서 다시 도출할 필요 없이 이 값을 해당 경로에 그대로 넣을 수 있습니다. pattern은 RouterProviderSegment와 RouterModelSegment를 단일 /로 이어 붙인 것이고, maxLength는 두 값의 길이 합에 그 구분자를 더한 값입니다.타입: RouterModelId — 모델 ID, 예: anthropic/claude-opus-4-6, 최대 193자RouterProviderSegment
필수
정식
{provider}/{model} 모델 ID에서 소문자로 표기되는 provider 세그먼트이며, 모델을 지정하는 대상 파트너를 나타냅니다. 호출 라우트의 provider 경로 매개변수와 카탈로그 항목의 provider 필드가 모두 이 하나의 스키마를 참조하며, 이것이 나열된 ID와 허용되는 ID가 서로 어긋나지 않게 유지합니다.타입: RouterProviderSegment — 영숫자 슬러그, 예: anthropic, 최대 64자RouterModelSegment
필수
정식
{provider}/{model} 모델 ID에서 소문자로 표기되는 model 세그먼트이며, 해당 공급자 안에서 실행할 모델을 나타냅니다. 호출 라우트의 model 경로 매개변수와 카탈로그 항목의 model 필드에서 공유되며, RouterProviderSegment와 마찬가지로 ID가 어긋나지 않게 하기 위한 것입니다.타입: RouterModelSegment — 영숫자 슬러그, 예: claude-opus-4-6, 최대 128자RouterModelBilling
필수
호출 전에 호출자가 알아야 하는 모델별 청구 정보이며, 가격이 아닙니다. 사용량과 비용 수치는 여기에 절대 나타나지 않습니다.타입:
RouterModelBillingRouterModelListResponse
Router 모델 카탈로그의 한 페이지입니다. 필드array of RouterModelListEntry
필수
이 페이지의 모델들로, 최대
limit개입니다.유형: RouterModelListEntry의 배열boolean
필수
이 페이지 뒤에 다른 페이지가 있는지 여부입니다. 이 값이 참인 동안 계속 순회하세요. 짧거나 빈
data로 카탈로그의 끝이라고 추측하지 마세요.RouterPageCursor
Router 목록에 대한 불투명 커서입니다. 서버에서 생성되며 오직 왕복 전달만 됩니다. 즉, 오프셋도 아니고, 모델 ID도 아니고, 정렬되지 않으며, 카탈로그 재구축 간에 안정적이지 않으므로, 이를 파싱하거나 값을 증가시키거나 그것이 나온 순회를 넘어 보관하는 것은 모두 계약 밖입니다. 오프셋이 아니라 커서인 이유는 카탈로그가 움직이는 목록이기 때문입니다. 오프셋 순회는 순회 도중 항목이 추가되거나 제거되면 조용히 항목을 건너뛰거나 반복하며, 호출자는 그런 일이 발생했는지 알 수 없습니다.유형:
RouterPageCursor, next_cursor로 반환되는 불투명 커서, 1–512자integer
필수
실제로 제공된 페이지 크기입니다. 최대값을 초과하여 요청한
limit은 거부되지 않고 최대값으로 제한되므로, 이 값은 요청한 값보다 작을 수 있습니다. 보낸 값이 아니라 이 값으로 페이지네이션하세요. 그렇지 않으면 받지도 못한 행을 받았다고 가정하게 됩니다.1–100RouterModelOutput
모델 결과 객체입니다. 정확한 형태를 확인하려면 선택된 모델의 출력 스키마를 참조하세요. 유형:object
RouterModelSegment
{provider}/{model} 모델 ID에서 모델 부분입니다.
Type: string — 영숫자 슬러그입니다(예: claude-opus-4-6). 최대 128자입니다.
RouterPageCursor
불투명한 카탈로그 커서입니다.cursor로 그대로 다시 전달하세요.
유형: string — next_cursor로 반환되는 불투명 커서, 1–512자
RouterProviderSegment
{provider}/{model} 모델 ID에서 공급자 부분입니다.
유형: string — 영숫자 슬러그, 예: anthropic, 최대 64자
RouterQueueCancelResponse
이 라우트가 처리한 요청을 설명하는 두 상태 코드, 즉202와 400에 대한 취소 요청에 대한 응답입니다. 성공 envelope과 오류 envelope을 따로 두지 않고 두 상태 모두에 하나의 body 형태를 사용합니다. 두 경우 모두 동일한 진술, 즉 취소가 발견한 내용을 나타내며, 상태 코드마다 다른 타입을 파싱해야 하는 클라이언트는 이러한 분리에서 얻는 것이 없기 때문입니다.
필드
RouterQueueRequestId
필수
대기 중인 Router 요청 하나의 식별자입니다. 호출자가 폴링하고 취소하고 결과를 수집할 때 사용하는 핸들입니다.타입:
RouterQueueRequestId — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자RouterQueueCancelStatus
필수
이 라우트가 실제로 처리한 요청을 설명하는 두 결과에 대해, 취소 요청이 발견한 내용입니다. 두 결과 모두 HTTP 상태 코드에 반영되므로, 클라이언트는 둘 중 어느 것으로도 분기할 수 있습니다.타입:
RouterQueueCancelStatusRouterQueueCancelStatus
취소 요청이 확인한 결과로, 이 라우트가 실제로 처리한 요청을 설명하는 두 가지 결과에 해당합니다. 두 결과 모두 HTTP 상태로 그대로 반영되므로, 클라이언트는 둘 중 어느 쪽을 기준으로 분기해도 됩니다. 타입:string
RouterQueuePosition
응답이 생성된 그 순간, 실행 대기열에서 이 요청보다 앞에 있는 요청 수입니다. 0이면 이 요청이 맨 앞에 있습니다. 유형:integer — 최소 0
RouterQueueRequestId
대기 중인 Router 요청 하나의 식별자입니다. 호출자가 폴링하고 취소하며 결과를 수집할 때 사용하는 핸들입니다. 유형:string — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자
RouterQueueStatus
대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며,RouterErrorType과 달리 이것은 닫힌 enum입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. RouterErrorType은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식할 수 없는 버킷을 단호히 거부하는 생성된 클라이언트는 이미 무언가 잘못된 바로 그 시점에 가장 심하게 실패하게 됩니다. 이쪽은 라이프사이클이며, 나중에 네 번째 상태가 추가되는 라이프사이클은 enum으로 선언되었든 아니든 이를 대상으로 작성된 모든 폴링 루프에 호환성을 깨뜨리는 변경입니다. 그래서 enum으로 선언되며, 제약은 클라이언트가 볼 수 있는 곳에 명시됩니다.
타입: string
RouterQueueStatusFields
RouterQueueStatusResponse에서 URL 블록이 아닌 나머지 절반입니다. 대기 중인 요청 하나의 식별자, 현재 상태, 그리고 그 상태가 터미널이고 실행이 성공하지 못했을 때 그 이유를 나타내는 포괄적 분류입니다.
필드
RouterQueueRequestId
필수
대기 중인 Router 요청 하나의 식별자입니다. 호출자가 폴링하고 취소하고 결과를 수집할 때 사용하는 핸들입니다.유형:
RouterQueueRequestId — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자RouterQueueStatus
필수
대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며,
RouterErrorType과 달리 이것은 닫힌 enum입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. RouterErrorType은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식할 수 없는 분류를 강하게 거부하는 생성된 클라이언트는 무언가가 이미 잘못된 바로 그 순간에 가장 심하게 실패하게 됩니다. 이 스키마는 라이프사이클이고, 나중에 네 번째 상태가 추가된 라이프사이클은 enum으로 선언되었든 아니든 그에 맞춰 작성된 모든 폴링 루프에 대한 호환성을 깨는 변경입니다. 그래서 enum으로 선언하고, 클라이언트가 볼 수 있는 위치에 제약을 명시합니다.유형: RouterQueueStatusRouterQueuePosition
응답이 구성된 즉시, 실행 대기열에서 이 요청보다 앞에 있는 요청이 몇 개인지입니다. 0은 이 요청이 맨 앞에 있음을 의미합니다.유형:
RouterQueuePosition — 최소 0RouterErrorType
성공하지 못한
COMPLETED 요청에만 존재하며, 결과 조회가 해당 실패를 반환할 때 X-Comfy-Error-Type에 붙이는 것과 동일한 포괄적 분류를 담습니다. 성공한 터미널 요청과 실패했거나 취소된 요청을 구분하는 역할을 합니다(둘 모두를 위한 별도의 터미널 상태는 없습니다). 그리고 성공 시에는 null이 아니라 아예 존재하지 않으므로, 존재 여부로 분기하세요.유형: RouterErrorTypeRouterQueueStatusResponse
대기 중인 요청 하나의 현재 상태이며, 제출 시 반환된 것과 동일한 세 개의 URL로 구성됩니다.RouterQueueUrls, RouterQueueStatusFields를 구성합니다.
타입: object
RouterQueueSubmitFields
RouterQueueSubmitResponse에서 URL 블록이 아닌 나머지 절반: 새 요청의 식별자와 요청이 접수된 순간의 상태입니다.
필드
RouterQueueRequestId
필수
대기 중인 Router 요청 하나의 식별자로, 호출자가 폴링하고 취소하고 결과를 수집할 때 사용하는 핸들입니다.Type:
RouterQueueRequestId — pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$, uuid, 최대 36자RouterQueueStatus
필수
대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며,
RouterErrorType과 달리 이쪽은 닫힌 enum입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. RouterErrorType은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식할 수 없는 분류값을 강하게 거부하는 생성된 클라이언트는 이미 문제가 발생한 바로 그 시점에 가장 심하게 실패하게 됩니다. 이쪽은 라이프사이클이고, 나중에 네 번째 상태가 추가된 라이프사이클은 enum으로 선언되었든 아니든 그에 맞춰 작성된 모든 폴링 루프에 대한 호환성을 깨는 변경입니다. 그래서 enum으로 선언하고, 제약을 클라이언트가 볼 수 있는 곳에 명시합니다.Type: RouterQueueStatusRouterQueuePosition
응답이 구성된 순간에 실행 대기열에서 이 요청보다 앞에 있는 요청의 수입니다. 0이면 이 요청이 맨 앞에 있습니다.Type:
RouterQueuePosition — 최소 0RouterCostEstimate
이 요청에 대한 사전 비용 추정치로, 호출자에게 비용 추정이 활성화된 경우 새로 접수될 때 포함됩니다. 이 요청이 고정된 공급자 구간을 제시합니다(실행 대기열에는 폴백 루프가 없으므로
fallback_provider가 실제로 실행되는 구간을 바꾸는 일은 없습니다). 수치를 제시할 수 없을 때도 source: unknown과 함께 여전히 포함되며, 추정치 때문에 제출이 실패하는 일은 없습니다. 멱등 재실행(Idempotent-Replayed: true)에서는 원본 견적이 저장되지 않으므로 생략됩니다. 이는 가격 고정이 아닙니다: 실행은 평가될 때 적용되는 요금으로 청구됩니다.Type: RouterCostEstimateRouterQueueSubmitResponse
실행이 실행 대기열에 승인될 때 반환되는 핸들로, 요청의 식별자와 상태에 나머지 수명 주기를 처리하는 세 개의 URL을 결합한 것입니다.RouterQueueUrls, RouterQueueSubmitFields를 구성합니다.
유형: object
RouterQueueUrls
대기 중인 한 요청의 남은 수명을 다루는 세 가지 URL입니다. 활성 핸들을 포함하는 모든 응답에서 반환되므로, 클라이언트가 실행 대기열 URL을 직접 조합할 일이 없습니다. 필드string
필수
이 요청의 상태 조회를 위한 절대 URL입니다.URI
string
필수
이 요청의 결과를 수집하는 절대 URL입니다.URI
string
필수
취소를 요청하는 절대 URL입니다.URI
RouterValidationErrorContext
검증 규칙이 실패한 이유에 대해 공급자가 제공한 세부 정보입니다. Type:object
RouterValidationErrorDetail
필드 수준 검증 실패 하나입니다. 필드array of any
필수
문제가 된 필드의 경로이며, 가장 바깥쪽 세그먼트가 먼저 옵니다. 예를 들어
["body", "image_url"], 또는 정수가 배열의 인덱스를 가리키는 ["body", "images", 0]과 같습니다.string
필수
이 단일 실패에 대한 사람이 읽을 수 있는 설명입니다.
string
필수
이 실패에 대한 구체적이고 기계가 읽을 수 있는 이유이며, 공급자로부터 변경 없이 그대로 전달됩니다. 타입이 지정된 SDK 예외 계층이 분기하는 값이 바로 이것이며, 응답 헤더의
error_type은 그것의 포괄적인 분류일 뿐입니다.RouterValidationErrorContext
하나의
RouterValidationErrorDetail에 대해 위반된 경계값으로, 공급자로부터 그대로 전달됩니다. 예를 들어 greater_than과 함께 오는 {"limit_value": 8}, image_too_small과 함께 오는 {"min_width": 512}, 또는 file_too_large와 함께 오는 {"max_size_bytes": 10485760}과 같습니다. 키 집합은 공급자와 오류 유형에 따라 다르므로 이는 의도적으로 열린 객체입니다. 이것을 고정된 필드 목록으로 좁히거나 msg 문자열에 접어 넣는 것이야말로, 포팅된 통합이 컴파일은 되지만 경계값을 읽던 분기를 조용히 잃게 되는 바로 그 방식입니다. 오류 유형에 경계값이 없으면 이 필드는 생략됩니다.Type: RouterValidationErrorContextRouterValidationErrorInput
문제가 된 입력 값으로, 호출자가
loc에서 다시 도출하지 않고도 무엇이 거부되었는지 볼 수 있도록 그대로 되돌려 전달됩니다. 문자열, 숫자, 논리값, 배열, 객체 또는 null 등 모든 JSON 타입이므로, 이 스키마는 객체로 좁히지 않고 의도적으로 타입 없이 둡니다. 공급자가 입력을 되돌려 전달하지 않으면 이 필드는 생략됩니다.Type: RouterValidationErrorInputRouterValidationErrorInput
거부된 입력 값이며, 공급자가 이를 포함하는 경우에 해당합니다.RouterValidationErrorResponse
422 검증 오류 본문입니다. 카테고리는 X-Comfy-Error-Type을 확인하세요.
필드
array of RouterValidationErrorDetail
필수
요청에서 발견된 모든 검증 실패 항목으로, 문제가 있는 필드마다 하나의 항목이 대응합니다.유형:
RouterValidationErrorDetail의 배열