> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-matt-router-pricing-pika-and-guard.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Comfy Router API 레퍼런스

> Comfy API 계약에서 생성된 모든 Comfy Router 엔드포인트, 매개변수, 응답 본문 및 오류 버킷.

<div className="router-api-reference-marker" />

Comfy Router의 정식 라우트로, 모델 ID로 주소가 지정됩니다.

기본 URL: `https://api.comfy.org`

아래의 모든 엔드포인트에는 인증이 필요합니다. `X-API-Key: <api-key>` 또는 `Authorization: Bearer <jwt>`를 전송하십시오.

Comfy API 키는 Bearer 토큰으로도 전송할 수 있습니다. 두 자격 증명 헤더를 모두 제공하면 `X-API-Key`가 우선합니다. 키와 JWT의 구분은 [인증 헤더](/ko/development/comfy-router/headers#요청-헤더)를, 액세스 요구 사항은 [퀵스타트](/ko/development/comfy-router/quickstart)를 참고하십시오.

## 엔드포인트

### `GET /v2/models`

**Comfy Router가 실행할 수 있는 모델을 나열합니다.**

사용 가능한 모델 ID와 과금 정보를 나열합니다. `has_more`가 참인 동안 `next_cursor`를 사용하세요.

**파라미터**

<ParamField query="cursor" type="RouterPageCursor">
  불투명 페이지네이션 커서입니다.

  Type: [`RouterPageCursor`](#routerpagecursor) -- `next_cursor`로 반환되는 불투명 커서, 1–512자
</ParamField>

<ParamField query="limit" type="integer">
  한 페이지에 반환할 모델 수입니다.

  최대 100, 기본값: 20
</ParamField>

**응답**

<ResponseField name="200" type="RouterModelListResponse">
  OK - 모델 카탈로그의 한 페이지입니다.

  Body: [`RouterModelListResponse`](#routermodellistresponse) -- Headers: `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="400" type="RouterErrorResponse">
  잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 이 요청이 허용되지 않습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

### `GET /v2/models/{provider}/{model}`

**정식 모델 ID로 파트너 모델 하나의 카탈로그 항목을 조회합니다.**

전체 카탈로그를 나열하지 않고 모델 하나의 세부 정보를 조회합니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정식 `{provider}/{model}` 모델 ID의 공급자 부분입니다.

  유형: [`RouterProviderSegment`](#routerprovidersegment). 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정식 `{provider}/{model}` 모델 ID의 모델 부분입니다.

  유형: [`RouterModelSegment`](#routermodelsegment). 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

**응답**

<ResponseField name="200" type="RouterModelDetail">
  OK: 모델의 카탈로그 항목입니다.

  본문: [`RouterModelDetail`](#routermodeldetail), 헤더: `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse), 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse), 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse), 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse), 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

### `POST /v2/models/{provider}/{model}`

**정규 모델 ID로 파트너 모델을 동기식으로 실행합니다.**

모델을 실행하고 완료된 결과를 같은 응답에서 받습니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정규 `{provider}/{model}` 모델 ID의 공급자 부분입니다.

  유형: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정규 `{provider}/{model}` 모델 ID의 모델 부분입니다.

  유형: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  하나의 논리적 호출을 다시 시도해도 안전하게 만드는 호출자 생성 키입니다.

  1–255자
</ParamField>

<ParamField query="model_provider" type="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`인 경우에 거부되는 대신 아무 효과가 없습니다.
</ParamField>

<ParamField query="strict_mode" type="boolean">
  `model_provider`와 함께일 때만 의미가 있습니다.

  기본값: False
</ParamField>

<ParamField query="fallback_provider" type="string">
  첫 시도가 Router 또는 시도한 공급자에게 귀속되는 이유로 실패했을 때 Router가 이 호출을 모델의 다른 등록된 공급자에 대해 재시도할지 여부를 제어합니다. 생략하거나 `false` 이외의 값을 지정하면 폴백이 켜진 상태로 유지되고, `false`는 폴백을 끕니다. 성공한 폴백 응답에는 `X-Comfy-Router-Fallback-Provider`가 포함됩니다. BYOK 자격 증명을 확인한 요청에서는 이 파라미터가 무엇을 말하든 폴백을 사용할 수 없습니다. 시도가 아예 이루어지지 않고 첫 실패가 그대로 전달되며, 이는 거부가 아니라 아무 효과가 없는 것입니다. 여기서 `409`가 발생하지 않습니다. 같은 이유로, 본문이 멀티파트 작업을 선택하는 요청과 `strict_mode=true`인 경우에도 마찬가지입니다. 각각은 호출을 다른 공급자에 대해 충실히 재현할 수 없는 하나의 공급자에 묶기 때문에, 폴백은 거부되지 않고 단순히 건너뜁니다. 명시적인 `model_provider`만이 그 `409`로 거부되며, 이 무조건적 건너뜀과 달리 그 멀티파트 `409`는 변환기가 작업을 처리할 수 없는 경로에만 적용됩니다.
</ParamField>

<ParamField query="reject_unknown_fields" type="boolean">
  이 모델의 입력 스키마가 선언하지 않은 최상위 요청 본문 필드를 수락하는 대신 거부하도록 선택합니다. 중첩 필드는 검사되지 않으며, 스키마가 선언되지 않은 필드를 허용하거나 작성된 스키마가 없는 모델에서는 아무것도 거부되지 않고, `strict_mode=true`와 함께 전송된 대기 중 제출에서도 마찬가지입니다.

  기본값: False
</ParamField>

**요청 본문**

`application/json` -- [`RouterModelInput`](#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`가 대체 공급자를 선택하는 경우, 조건이 지정된 각 작업은 해당 공급자 자체의 요율로 과금될 수 있습니다.

**응답**

<ResponseField name="200" type="RouterModelOutput">
  정상 - `model_provider`가 없거나, `model_provider`와 `strict_mode=false`(기본값, 가능하면 이 모델의 네이티브 계약으로 다시 변환되고, 변환에 실패하면 대체 공급자의 원시 응답으로 폴백합니다. 항상 로그에 기록되며 결코 조용히 넘어가지 않습니다)를 함께 보낸 경우 형태는 이 모델 자체의 네이티브 출력입니다. `strict_mode=true`인 경우에는 대체 공급자의 응답이 변경 없이 그대로 반환됩니다. 파트너가 생성 결과를 바이트로 직접 응답하는 모델의 경우, 본문은 `application/json`이 아니라 파트너 자체의 `Content-Type`을 따르는 해당 바이트입니다. 응답 `Content-Type`을 기준으로 분기하고 JSON 문서라고 가정하지 마세요.

  본문: [`RouterModelOutput`](#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-Remaining`
</ResponseField>

<ResponseField name="400" type="RouterErrorResponse">
  잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`, `X-Comfy-Upstream-Detail`, `X-Comfy-Refusal-Subject`, `Idempotent-Replayed`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="402" type="RouterErrorResponse">
  Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="409" type="RouterErrorResponse">
  `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`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After`(`concurrency_limit_exceeded`인 경우)
</ResponseField>

<ResponseField name="413" type="RouterErrorResponse">
  요청 본문이 너무 큽니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="422" type="RouterValidationErrorResponse">
  요청의 내용이 모델의 스키마에 대해 거부되었습니다.

  본문: [`RouterValidationErrorResponse`](#routervalidationerrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed`
</ResponseField>

<ResponseField name="429" type="RouterErrorResponse">
  `X-Comfy-Error-Type`을 확인하세요. `concurrency_limit_exceeded`는 진행 중인 호출을 줄이라는 뜻이고, `rate_limited`는 허용 창을 기다리라는 뜻입니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining`
</ResponseField>

<ResponseField name="502" type="RouterErrorResponse">
  공급자 자체의 응답을 결과로 변환할 수 없습니다(`provider_error`).

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After`(용량 거부인 경우에만)
</ResponseField>

<ResponseField name="504" type="RouterErrorResponse">
  요청이 데드라인을 초과했습니다. 재시도하기 전에 오류 유형을 확인하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`, `Retry-After`
</ResponseField>

### `POST /v2/models/{provider}/{model}/estimate`

**실행하지 않고도 실행 전에 모델 호출의 가격을 산정합니다.**

이 모델에서 이 본문을 실행할 때 Comfy가 청구할 금액을 미국 달러로 반환하며, 청구가 이루어지는 것과 동일한 요율표를 기준으로 가격이 산정됩니다. 본문은 먼저 모델의 입력 스키마에 대해 검증되며, 이는 기본 실행(`strict_mode` 없음, `reject_unknown_fields` 없음)이 검증하는 방식과 같습니다. 따라서 모델의 스키마를 통과하지 못하는 본문은 여기서도 실행 시와 동일한 `422`입니다. 공급자에게 아무것도 전달되지 않고 아무것도 청구되지 않습니다. 이 응답은 가격을 고정하는 것이 아닙니다. `pricing_as_of` 시점에 유효한 요율로 산정되며, 실행은 요율이 책정되는 시점에 유효한 요율로 청구됩니다. 기능이 순차 배포되는 동안 이 라우트는 `error_type: not_enabled`와 함께 `403`을 응답합니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정식 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트로, 모델을 실행하는 파트너입니다.

  Type: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정식 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다.

  Type: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField query="model_provider" type="string">
  이 모델을 제공할 대체 공급자를 선택합니다. 현재의 기본 공급자 대신 사용됩니다.
</ParamField>

**요청 본문**

`application/json` -- [`RouterModelInput`](#routermodelinput) (필수)

파트너 모델의 네이티브 JSON 입력으로, 이 모델에 대해 동기 라우트가 받는 본문과 동일합니다. 기본 실행이 검증하는 방식대로 모델 자체의 입력 스키마에 대해 검증되며(이 라우트는 `strict_mode`나 `reject_unknown_fields`를 받지 않습니다), 본문 자체의 필드(출력 개수, 입력 이미지가 선택하는 작업)가 무엇의 가격을 산정할지 결정합니다.

**응답**

<ResponseField name="200" type="RouterCostEstimate">
  견적입니다.

  Body: [`RouterCostEstimate`](#routercostestimate) -- Headers: `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="400" type="RouterErrorResponse">
  잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="413" type="RouterErrorResponse">
  요청 본문이 너무 큽니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="422" type="RouterValidationErrorResponse">
  견적 요청의 본문이 모델의 스키마에 의해 거부되었거나, 경로에 지정된 것과 다른 모델을 지정했습니다.

  Body: [`RouterValidationErrorResponse`](#routervalidationerrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` (용량 거부에만 해당)
</ResponseField>

### `GET /v2/models/{provider}/{model}/openapi.json`

**파트너 모델 하나의 입력 및 출력 스키마를 OpenAPI 문서로 읽어옵니다.**

모델 하나의 입력 및 출력 스키마를 독립형 OpenAPI 문서로 읽어옵니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정규 `{provider}/{model}` 모델 ID의 공급자 부분입니다.

  유형: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정규 `{provider}/{model}` 모델 ID의 모델 부분입니다.

  유형: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField header="If-None-Match" type="string">
  호출자가 이전 `200` 응답에서 보유한 `ETag`입니다.
</ParamField>

**응답**

<ResponseField name="200" type="RouterModelInputSchemaDocument">
  OK - 모델의 입력 및 출력 스키마를 독립형 OpenAPI 문서로 반환합니다.

  본문: [`RouterModelInputSchemaDocument`](#routermodelinputschemadocument) -- 헤더: `X-Comfy-Request-Id`, `ETag`, `Cache-Control`
</ResponseField>

<ResponseField name="304" type="no body">
  Not Modified - 호출자가 `If-None-Match`로 보낸 `ETag` 이후 문서가 변경되지 않았습니다.

  헤더: `X-Comfy-Request-Id`, `ETag`, `Cache-Control`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="500" type="RouterErrorResponse">
  Router가 요청을 완료할 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

### `POST /v2/models/{provider}/{model}/requests`

**파트너 모델 실행을 실행 대기열에 제출하고 즉시 반환합니다.**

Comfy Router의 대기 중 전달 모드입니다. 요청 본문은 `POST /v2/models/{provider}/{model}`가 이 모델에 대해 허용하는 것과 동일한 파트너 네이티브 JSON 입력입니다. 하나의 본문 형태, 모델별 스키마 하나, 두 가지 전달 모드가 있습니다. 다만 이 라우트는 결과를 위해 연결을 유지하지 않습니다. 실행을 접수하고 핸들과 함께 `201`로 응답하며, 호출자는 아래 세 가지 조회를 통해 나중에 결과를 수집합니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트로, 모델을 실행할 대상 파트너입니다.

  유형: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다.

  유형: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField query="model_provider" type="string">
  현재 기본값 대신 이 모델을 제공할 대체 공급자를 선택합니다.
</ParamField>

<ParamField query="strict_mode" type="boolean">
  `model_provider`와 함께 사용할 때만 의미가 있습니다.

  기본값: False
</ParamField>

<ParamField header="Idempotency-Key" type="string">
  호출자가 생성하는 키로, 하나의 논리적 호출을 안전하게 재시도할 수 있게 합니다.

  1–255자
</ParamField>

<ParamField query="reject_unknown_fields" type="boolean">
  이 모델의 입력 스키마가 선언하지 않은 최상위 요청 본문 필드를 수용하는 대신 거부하도록 선택합니다. 중첩 필드는 검사하지 않으며, 스키마가 선언되지 않은 필드를 허용하거나 작성된 스키마가 없는 모델의 경우, 또는 `strict_mode=true`로 전송된 대기 중 제출에서는 아무것도 거부되지 않습니다.

  기본값: False
</ParamField>

**요청 본문**

`application/json` -- [`RouterModelInput`](#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` 참조).

**응답**

<ResponseField name="201" type="RouterQueueSubmitResponse">
  생성됨 - 실행이 실행 대기열에 접수되었습니다.

  본문: [`RouterQueueSubmitResponse`](#routerqueuesubmitresponse) -- 헤더: `X-Comfy-Request-Id`, `Idempotent-Replayed`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="400" type="RouterErrorResponse">
  잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="413" type="RouterErrorResponse">
  요청 본문이 너무 큽니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="402" type="RouterErrorResponse">
  Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자나 모델에 대해 요청이 허용되지 않습니다. 파트너가 생성을 바이트로 직접 응답하는 모델은 아직 실행 대기열에 넣을 수 없으며 `not_enabled`로 거부됩니다. 대신 동기 라우트에서 실행하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="409" type="RouterErrorResponse">
  `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`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` (`concurrency_limit_exceeded`인 경우)
</ResponseField>

<ResponseField name="422" type="RouterValidationErrorResponse">
  요청 내용이 모델의 스키마와 일치하지 않아 거부되었습니다.

  본문: [`RouterValidationErrorResponse`](#routervalidationerrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` (용량 거부에만 해당)
</ResponseField>

### `GET /v2/models/{provider}/{model}/requests/{request_id}`

**제출된 요청 하나의 결과를 수집합니다.**

수집 엔드포인트입니다. 성공적으로 완료된 요청에 대해서는 파트너 모델 자체의 네이티브 출력을 반환합니다. 이는 동일한 모델과 동일한 입력에 대해 동기 라우트의 `200`이 담는 것과 바이트 단위로 동일합니다. 따라서 두 전달 방식은 하나의 결과 형태를 만들어내며, 호출자는 두 번째 파서 없이 두 방식 사이를 오갈 수 있습니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트입니다. 모델이 실행되는 파트너입니다.

  유형: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트입니다. 해당 공급자 내에서 실행할 모델입니다.

  유형: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField path="request_id" type="RouterQueueRequestId" required>
  대상으로 삼을 대기 중 요청입니다. 제출 시 본문에서 반환된 `request_id`입니다.

  유형: [`RouterQueueRequestId`](#routerqueuerequestid) -- `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 최대 36자
</ParamField>

**응답**

<ResponseField name="200" type="RouterModelOutput">
  OK - 결과를 생성한 요청, 즉 성공적으로 완료된 요청이거나 기록된 과금과 저장된 결과를 모두 가진 터미널 요청에 대해 저장된 결과입니다. 파트너 자체의 미디어 타입으로 변경 없이 반환되며, 동기 라우트의 `200`이 반환하는 방식과 정확히 동일하고, 제출이 수락한 것과 동일한 공급자 선택 계약을 따릅니다. `model_provider` 없이, 또는 `model_provider`와 함께 `strict_mode=false`(기본값, 가능한 경우 이 모델의 네이티브 계약으로 다시 변환되며, 변환에 실패하면 대체 공급자 자체의 원시 응답으로 폴백합니다. 이는 기록되며 결코 조용히 넘어가지 않습니다)인 경우 형태는 이 모델 자체의 네이티브 출력입니다. `strict_mode=true`이면 대체 공급자의 응답이 변경 없이 반환됩니다. 파트너가 생성 결과를 바이트로 직접 응답하는 모델의 경우, 본문은 `application/json`이 아니라 파트너 자체의 `Content-Type` 아래에 있는 해당 바이트입니다. 응답 `Content-Type`을 기준으로 분기하고 JSON 문서라고 가정하지 마십시오.

  본문: [`RouterModelOutput`](#routermodeloutput) 또는 원시 바이트(`*/*`) -- 헤더: `X-Comfy-Request-Id`, `X-Content-Type-Options`
</ResponseField>

<ResponseField name="202" type="RouterQueueStatusResponse">
  Accepted - 요청이 아직 완료되지 않았습니다.

  본문: [`RouterQueueStatusResponse`](#routerqueuestatusresponse) -- 헤더: `X-Comfy-Request-Id`, `Retry-After`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해 요청이 허용되지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="410" type="RouterErrorResponse">
  Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하십시오.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="409" type="RouterErrorResponse">
  요청이 작업과 충돌하는 상태입니다. 오류 유형을 확인하십시오.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="504" type="RouterErrorResponse">
  요청이 데드라인을 초과했습니다. 재시도하기 전에 오류 유형을 확인하십시오.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="422" type="RouterValidationErrorResponse">
  요청의 내용이 모델의 스키마에 대해 거부되었습니다.

  본문: [`RouterValidationErrorResponse`](#routervalidationerrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed`
</ResponseField>

<ResponseField name="default" type="RouterErrorResponse">
  Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

### `PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel`

**제출된 요청 하나에 대해 취소를 요청합니다.**

아직 끝나지 않은 요청을 중지하도록 Comfy에 요청합니다. 이는 요청일 뿐 보장이 아니며, `202`는 바로 그 점을 나타냅니다. `CANCELLATION_REQUESTED`는 요청이 접수되었다는 뜻이지 실행이 중지되었다는 뜻이 아닙니다. 파트너에서 이미 전송 중인 실행은 그대로 완료될 수 있으며, 완료된 파트너 생성은 누군가 결과를 수집했는지와 무관하게 과금됩니다. 따라서 실제로 무슨 일이 일어났는지 알아야 하는 호출자는 이후 상태 엔드포인트를 조회해야 합니다. 이때 실제로 적용된 취소는 다른 모든 최종 결과와 마찬가지로 `error_type`을 함께 지닌 `COMPLETED`로 나타납니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트로, 실행되는 모델의 파트너입니다.

  Type: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다.

  Type: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField path="request_id" type="RouterQueueRequestId" required>
  처리할 대기 중 요청으로, 제출 시 본문에서 반환된 `request_id`입니다.

  Type: [`RouterQueueRequestId`](#routerqueuerequestid) -- `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 최대 36자
</ParamField>

**응답**

<ResponseField name="202" type="RouterQueueCancelResponse">
  수락됨 - `CANCELLATION_REQUESTED`.

  Body: [`RouterQueueCancelResponse`](#routerqueuecancelresponse) -- Headers: `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="409" type="RouterQueueCancelResponse">
  충돌 - `ALREADY_COMPLETED`.

  Body: [`RouterQueueCancelResponse`](#routerqueuecancelresponse) -- Headers: `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="400" type="RouterErrorResponse">
  잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 해당 요청이 허용되지 않습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="default" type="RouterErrorResponse">
  Router 요청 수준의 실패로, 요청이 모델에 도달하지 않았거나 모델 자체가 보고하지 않은 이유로 실패한 경우입니다.

  Body: [`RouterErrorResponse`](#routererrorresponse) -- Headers: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

### `GET /v2/models/{provider}/{model}/requests/{request_id}/status`

**제출된 요청 하나의 실행 대기열 상태를 조회합니다.**

폴링 엔드포인트입니다. 요청의 현재 상태만 응답하며 결과는 반환하지 않습니다. 따라서 클라이언트는 매 폴링마다 출력을 전송받지 않고도 오래 걸리는 생성 작업을 지켜볼 수 있습니다. 결과는 이 응답이 `COMPLETED`를 나타낼 때 아래의 조회를 통해 한 번만 수집합니다.

**파라미터**

<ParamField path="provider" type="RouterProviderSegment" required>
  정식 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트입니다. 모델을 실행하는 파트너입니다.

  유형: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ParamField>

<ParamField path="model" type="RouterModelSegment" required>
  정식 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트입니다. 해당 공급자 내에서 실행할 모델입니다.

  유형: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ParamField>

<ParamField path="request_id" type="RouterQueueRequestId" required>
  처리할 대기 중 요청입니다. 제출 시 본문에서 반환된 `request_id`입니다.

  유형: [`RouterQueueRequestId`](#routerqueuerequestid) -- `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 최대 36자
</ParamField>

**응답**

<ResponseField name="200" type="RouterQueueStatusResponse">
  OK - 요청의 현재 실행 대기열 상태입니다.

  본문: [`RouterQueueStatusResponse`](#routerqueuestatusresponse) -- 헤더: `X-Comfy-Request-Id`, `Retry-After`
</ResponseField>

<ResponseField name="401" type="RouterErrorResponse">
  자격 증명이 누락되었거나 유효하지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="403" type="RouterErrorResponse">
  이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="404" type="RouterErrorResponse">
  모델 ID를 찾을 수 없습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="410" type="RouterErrorResponse">
  Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="503" type="RouterErrorResponse">
  Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

<ResponseField name="default" type="RouterErrorResponse">
  Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다.

  본문: [`RouterErrorResponse`](#routererrorresponse) -- 헤더: `X-Comfy-Error-Type`, `X-Comfy-Request-Id`
</ResponseField>

여기의 설명은 간략합니다. 모델 선택, 검증, 재시도, 과금에 대해서는 [Comfy Router API 사용하기](/ko/development/comfy-router/api)를, 헤더 동작에 대해서는 [헤더](/ko/development/comfy-router/headers)를 참고하세요.

## 오류 버킷

기계가 읽을 수 있는 Router 오류 카테고리이며, `X-Comfy-Error-Type` 헤더로도 전송됩니다.

### 요청 수준 버킷

Router가 요청을 접수한 뒤 완료하지 못한 경우 발생합니다.

| `error_type` | 의미 |
| - | - |
| `invalid_input` | 요청이 모델에 도달하기 전에 거부되었습니다. 형식이 잘못된 본문, 형식이 잘못되었거나 만료된 페이지네이션 커서, 모델 자체 스키마가 허용하지 않는 입력, 또는 이 요청에 사용할 수 없는 `Idempotency-Key`(다른 요청에 이미 사용되었거나(방법, 경로와 쿼리, 또는 본문이 다름) 응답을 재생할 수 없는 호출에 이미 소비된 경우)입니다. |
| `content_policy_violation` | 공급자가 콘텐츠 정책을 이유로 요청을 거부했습니다. |
| `provider_error` | 파트너 공급자가 자체적인 실패를 보고했거나, Router가 결과로 해석할 수 없는 응답을 반환했습니다. |
| `provider_timeout` | 파트너 공급자가 자체 마감 시간 내에 응답하지 않았습니다. |
| `insufficient_credits` | 호출한 워크스페이스에 모델을 실행할 크레딧이 충분하지 않습니다. |
| `model_not_found` | `{provider}/{model}` ID가 Router가 실행할 수 있는 모델을 가리키지 않습니다. 알 수 없는 공급자, 등록되지 않은 ID, 카탈로그에서 서비스 종료 날짜가 지나 퇴출된 ID, 또는 공급자가 현재 Comfy용으로 제공하지 않는 카탈로그 ID입니다. |

### 전송 수준 버킷

모델 호출 이전이나 그 무렵에 Router 자체에서 발생합니다.

| `error_type` | 의미 |
| - | - |
| `unauthorized` | 요청에 사용할 수 있는 자격 증명이 없었습니다. |
| `forbidden` | 자격 증명은 유효하지만 이 모델이나 이 작업에 대한 권한이 없습니다. |
| `concurrency_limit_exceeded` | 워크스페이스에 이미 허용된 만큼의 호출이 진행 중입니다. 그중 하나가 끝나면 다시 시도하세요. |
| `client_disconnected` | Router가 결과를 반환하기 전에 호출자가 연결을 닫았습니다. |
| `internal_error` | Router 자체가 실패했습니다. |
| `deadline_exceeded` | 응답이 도착하기 전에 Comfy가 자체적으로 설정된 한도에서 연결 유지를 중단했습니다. |
| `not_enabled` | 이 호출자에 대해서는 Comfy Router가 아직 활성화되지 않았습니다. |
| `service_unavailable` | Comfy Router가 의존하는 서비스가 일시적으로 사용할 수 없으며, 호출자는 아무 잘못도 하지 않았습니다. |
| `rate_limited` | 호출자가 창을 기준으로 측정되는 허용량을 모두 소진했으며, 해당 창이 넘어갈 때까지 기다려야 합니다. |
| `cancelled` | 대기 중이던 요청이 결과를 생성하기 전에 취소 경로를 통해서든 운영자에 의해서든 철회되었습니다. 이는 터미널 상태이며, 그 자체로 요금 청구에 대한 진술은 아닙니다. |
| `queue_timeout` | 대기 중인 요청이 실행 대기열 타임아웃을 넘겨 대기했지만 결국 승인되지 않았습니다. |
| `request_not_found` | `request_id`가 이 모델에서 호출자의 요청 중 어느 것도 가리키지 않습니다. |
| `queue_backlog_full` | 호출자에게 이미 실행을 기다리는 대기 중 요청이 너무 많아 이 제출이 거부되었습니다. |

## 응답 헤더

<ResponseField name="Cache-Control" type="string">
  제공되는 스키마 문서에 대한 신선도 지시문입니다.
</ResponseField>

<ResponseField name="ETag" type="string">
  `GET /v2/models/{provider}/{model}/openapi.json`에 대해 제공되는 문서 바이트에 대한 강력한 엔티티 태그입니다.
</ResponseField>

<ResponseField name="Idempotent-Replayed" type="boolean">
  모델을 다시 실행한 것이 아니라 `Idempotency-Key`의 기록에서 이 응답이 제공된 경우 존재하며 `true`입니다.
</ResponseField>

<ResponseField name="Retry-After" type="integer">
  변경 없이 동일한 요청을 다시 보내기 전에 기다릴 초입니다.

  전송 시: `503`
</ResponseField>

<ResponseField name="Retry-After" type="integer">
  대기 중인 요청을 다음에 폴링하기 전에 기다릴 초입니다.

  전송 시: `200`, `202`
</ResponseField>

<ResponseField name="Retry-After" type="integer">
  동일한 `Idempotency-Key`로 동일한 요청을 재시도하기 전에 기다릴 초입니다.

  전송 시: `409`, `504`
</ResponseField>

<ResponseField name="X-Comfy-Credits-Used" type="string">
  이 실행에 든 비용을 Comfy 크레딧으로 나타낸 것으로, 청구 자체가 기준으로 삼는 것과 동일한 요금표에서 산정됩니다. 따라서 호출자는 자체 가격표가 필요 없으며, 유료 호출을 두 번 이상 거쳐 공급자에 도달한 실행에서는 마지막 호출의 값이 아니라 그 합계입니다.
</ResponseField>

<ResponseField name="X-Comfy-Error-Type" type="RouterErrorType">
  실패에 대한 대략적인 기계 판독 가능 버킷으로, Router가 모든 오류 응답에 설정합니다.

  타입: [`RouterErrorType`](#routererrortype)
</ResponseField>

<ResponseField name="X-Comfy-Refusal-Subject" type="string">
  콘텐츠 정책 거부가 입력 또는 출력 중 어느 쪽에 관한 것인지 나타내는 Router 수준의 폐쇄형 어휘입니다: `input`, `output`, `input_text`, `input_image`, `input_video`, `input_audio`, `output_text`, `output_image`, `output_video`, `output_audio`.
</ResponseField>

<ResponseField name="X-Comfy-Request-Id" type="string">
  이 호출에 대해 서버가 생성한 식별자로, 모든 Router 응답에 존재합니다. 성공, 4xx, 5xx 모두 마찬가지입니다. 오류 응답이야말로 사용자가 지원 요청에 인용할 id가 필요한 바로 그 순간이기 때문입니다.
</ResponseField>

<ResponseField name="X-Comfy-Router-Dropped-Params" type="string">
  문자열 배열을 담은 하나의 JSON 인코딩 문자열입니다. 쉼표로 분리하지 말고 JSON 파서로 디코딩하세요. 전송되는 값은 쉼표로 구분된 OpenAPI 배열이 아니라 단일 문자열이며, 각 항목은 그 자체로 쉼표를 포함하는 문장이기 때문입니다. 이 호출의 요청 본문을 변환한 결과 해당 공급자에서 하나 이상의 네이티브 필드를 정확히 표현할 수 없었을 때마다 존재하며, 누락된 각 필드와 그 이유를 명시합니다. 호출자가 `model_provider`로 해당 변환을 요청했든(`strict_mode=false`, 기본값) 자동 `fallback_provider` 재시도가 실행되었든 마찬가지입니다.
</ResponseField>

<ResponseField name="X-Comfy-Router-Fallback-Provider" type="string">
  `fallback_provider`가 실제로 이 호출을 두 번째 공급자에 대해 재시도했고 그 재시도가 성공한 경우에만 공급자 이름과 함께 존재합니다. 최종적으로 이 호출을 처리한 공급자이며, 시도되었다가 역시 실패한 공급자는 결코 아닙니다.
</ResponseField>

<ResponseField name="X-Comfy-Upstream-Detail" type="string">
  모델 공급자가 요청을 거부한 이유를 길이를 제한하고 정제하여 제시한 것입니다.
</ResponseField>

<ResponseField name="X-Comfy-Upstream-Status" type="integer">
  이 호출에 대한 모델 공급자 자체의 HTTP 상태입니다.
</ResponseField>

<ResponseField name="X-Committed-Spend-Current" type="integer">
  호출자가 현재 진행 중인 호출에 확정한 미국 달러 센트 금액입니다.
</ResponseField>

<ResponseField name="X-Committed-Spend-Limit" type="integer">
  호출자가 진행 중인 호출에 확정할 수 있는 파트너 지출의 상한(미국 달러 센트)입니다. 호출이 승인되는 순간부터 금액이 보류되고 해당 호출이 끝나면 해제됩니다.
</ResponseField>

<ResponseField name="X-Committed-Spend-Remaining" type="integer">
  상한 아래에 남은 여유분(미국 달러 센트)으로, 최소 0입니다.
</ResponseField>

<ResponseField name="X-Content-Type-Options" type="string">
  Router 모델의 모든 성공 실행에서 항상 `nosniff`입니다.
</ResponseField>

## 실행 전 비용 추정

`POST /v2/models/{provider}/{model}/estimate`는 본문을 실행하지 않고 가격을 산정하며, 대기 중 제출(`POST /v2/models/{provider}/{model}/requests`)은 `201` 응답에서 `estimate`와 동일한 [`RouterCostEstimate`](#routercostestimate)를 반환합니다. 둘 다 Comfy가 해당 실행에 청구하는 요율 카드를 기준으로 가격이 산정됩니다. 자체 공급자 키로 실행한 경우에는 Comfy가 청구하지 않습니다(아래 참조). 추정 기능이 점진적으로 배포되는 동안에는 이 경로가 `error_type: not_enabled`와 함께 `403`을 응답하고, 제출 응답에서는 `estimate`가 생략됩니다. 카탈로그에는 여전히 가격이 없습니다.

어떤 금액보다도 `source`를 먼저 확인하세요. 수치가 누락되었다고 해서 무료라는 뜻은 결코 아닙니다.

| `source` | 포함하는 항목 | 해석 방법 |
| - | - | - |
| `exact` | `amount`, `amount_cents`, `credits` | `pricing_as_of`의 요율로 이 본문에 대해 부과되는 요금입니다. |
| `estimated` | `min_amount`, `max_amount` 및 각각의 `_cents` 형태, `amount` 없음 | 요금은 공급자가 나중에 보고하는 수량에 따라 달라지며 본문이 그 범위를 정합니다. 두 경계 사이의 값이 될 것으로 예상됩니다. |
| `unknown` | `reason`, 수치 없음 | 실행 전에는 가격을 제시할 수 없습니다. 다른 모든 `source` 값은 `unknown`으로 취급하세요. |

`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을 대체합니다. 이 동작은 모델에 따라 다르며, 이를 선택하는 요청 헤더는 없습니다.

| 모델 | Comfy 스토리지로 복사되는 항목 | Comfy 호스팅 URL 최대 수명 |
| - | - | - |
| `bfl/*` | 완료된 에셋, 그리고 결과에 포함된 경우 드래프트 캐시 에셋 | 24시간 |
| `byteplus/*` 비디오 모델 (`seedance`, `dreamina-seedance`) | 완료된 비디오, 그리고 결과에 포함된 경우 마지막 프레임 이미지 | 24시간 |
| `minimax/*` | 완료된 비디오 | 12시간 |
| `xai/*` | 생성된 모든 이미지, 그리고 완료된 비디오 | 24시간 |

이 수명은 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` 매개변수는 재생할 수 없을 때 재시도에 무엇이 응답되는지 설명합니다.

<span id="per-model-input-schemas" />

## 모델별 입력 및 출력 스키마

각 모델의 필드는 `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` 대신 `*/*`를 사용할 수 있으므로, 디코딩하기 전에 응답 콘텐츠 타입을 확인하세요.

<h2 id="schemas">
  스키마
</h2>

<h3 id="routerchargesonpolicyrejection">
  RouterChargesOnPolicyRejection
</h3>

이 모델에 대해 콘텐츠 정책 거부가 청구되는지 여부입니다. 알 수 없는 값은 청구될 수 있는 것으로 간주하세요.

유형: `string`

### RouterCostEstimate

이 호출에 대해 Comfy가 청구할 금액으로, 디스패치 이전에 청구가 과금되는 것과 동일한 요율표를 기준으로 산정되며 미국 달러로 표시됩니다. `source`는 이 숫자를 얼마나 신뢰할 수 있는지 나타냅니다. `exact`는 `amount`를 포함하고, `estimated`는 `min_amount`와 `max_amount`를 포함하며 `amount`는 없고, `unknown`은 둘 다 없이 `reason`을 포함합니다. 누락된 `amount`를 무료로 해석하지 마세요. 가격 고정이 아닙니다. `pricing_as_of`를 참고하세요.

**필드**

<ResponseField name="source" type="string" required>
  `exact` | `estimated` | `unknown`; 그 외의 값은 `unknown`으로 해석합니다.
</ResponseField>

<ResponseField name="currency" type="string" required>
  항상 `USD`입니다.
</ResponseField>

<ResponseField name="amount" type="string">
  달러를 소수점 문자열로 나타낸 값입니다. 예: "0.04". 소수점 이하 최대 8자리이며 지수 표기를 쓰지 않습니다. 청구 대상이 되는 1센트 미만 가격은 "0"으로 표시되지 않습니다. `source`가 `exact`일 때만 존재합니다.
</ResponseField>

<ResponseField name="min_amount" type="string">
  달러 기준 하한값을 소수점 문자열로 나타낸 값입니다. `source`가 `estimated`일 때만 존재합니다.
</ResponseField>

<ResponseField name="max_amount" type="string">
  달러 기준 상한값을 소수점 문자열로 나타낸 값입니다. `source`가 `estimated`일 때만 존재합니다.
</ResponseField>

<ResponseField name="amount_cents" type="number">
  산술 연산에 쓰기 위해 같은 값을 반올림하지 않은 미국 센트 단위로 나타낸 값입니다. `amount`와 함께 존재합니다.

  double
</ResponseField>

<ResponseField name="min_amount_cents" type="number">
  반올림하지 않은 미국 센트 단위의 `min_amount`입니다. `min_amount`와 함께 존재합니다.

  double
</ResponseField>

<ResponseField name="max_amount_cents" type="number">
  미국 센트 단위의 `max_amount`입니다. `max_amount`와 함께 존재합니다.

  double
</ResponseField>

<ResponseField name="credits" type="number">
  플랫폼 환산율(\$1 = 211 크레딧)을 사용해 `amount`를 Comfy 크레딧으로 나타낸 값이며 소수점 이하 2자리로 반올림됩니다. `exact` 견적에 대해 `X-Comfy-Credits-Used`가 담게 될 값입니다.

  double
</ResponseField>

<ResponseField name="provider" type="string" required>
  이 견적이 대상으로 하는 공급자 구간입니다. 대기 중 제출에서는 실행될 구간입니다.
</ResponseField>

<ResponseField name="model" type="RouterModelId" required>
  정식 Comfy Router 모델 ID인 `{provider}/{model}`이며, `POST /v2/models/{provider}/{model}`에서 모델을 지정하는 값과 정확히 같습니다. 따라서 호출자는 다른 것에서 다시 도출할 필요 없이 이 값을 그 경로에 그대로 넣을 수 있습니다. 이 값의 `pattern`은 `RouterProviderSegment`와 `RouterModelSegment`를 단일 `/`로 연결한 것이고, `maxLength`는 두 값의 길이 합에 그 구분자를 더한 값입니다.

  Type: [`RouterModelId`](#routermodelid) -- 모델 ID, 예: `anthropic/claude-opus-4-6`, 최대 193자
</ResponseField>

<ResponseField name="pricing_as_of" type="string" required>
  이 견적을 산정할 때 사용한 요율표를 가져온 시각입니다. 실행은 이 시점이 아니라 요금이 산정되는 시점에 유효한 요율로 청구됩니다. 요율표를 읽지 않은 경우(`reason: pricing_unavailable`, `byok`, 또는 어떤 요율표로도 산정할 수 없는 `not_quotable` 호출)에는 이 값이 견적이 응답된 시각입니다.

  date-time
</ResponseField>

<ResponseField name="reason" type="string">
  `source`가 `unknown`일 때만 존재합니다. `not_quotable`(Router가 실행 전에 이 호출의 가격을 산정할 수 없음. 가격이 공급자가 보고하는 내용에 따라 달라지거나, 요청 본문이 청구 대상 수량을 한정하지 않는 경우), `unpriced_model`(요율표에 이 요청의 가격이 없음), `byok`(대기 중 제출에만 해당: 실행에 사용자의 공급자 키를 사용하므로 Comfy는 이에 대해 아무것도 청구하지 않음), 또는 `pricing_unavailable`(대기 중 제출에만 해당: 요청이 접수될 때 요율표를 읽을 수 없었음. 이는 일시적이며 실행은 평소와 같이 청구됨)입니다. 그 외의 값은 `not_quotable`로 해석합니다.
</ResponseField>

### RouterErrorResponse

인증, 접근, 모델 조회, 할당량 및 공급자 전송 실패에 대한 오류 본문입니다.

**필드**

<ResponseField name="detail" type="string" required>
  사람이 읽을 수 있는 실패 설명이며, 최종 사용자에게 그대로 보여줘도 안전합니다. 기계적으로 파싱되지 않으므로 대신 `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`을 기준으로 분기하는 것이 호환성 보장을 가지지 않습니다.
</ResponseField>

<ResponseField name="error_type" type="RouterErrorType" required>
  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: [`RouterErrorType`](#routererrortype)
</ResponseField>

<ResponseField name="upstream_detail" type="string">
  모델 공급자가 요청을 거부한 이유에 대해 정리되고 정제된 설명으로, `error_type`이 `invalid_input`이고 `X-Comfy-Upstream-Status`가 공급자의 `4xx` 또는 `2xx`일 때만 존재합니다. 즉, 공급자가 요청을 형식 오류로 거부하면서 그 이유를 밝힌 경우입니다. 보통 이 상태는 `4xx`이며, 거부된 생성을 성공 응답 봉투 안에 담아 보고하는 공급자의 경우 `2xx`입니다 (BytePlus의 실패한 작업 폴링은 HTTP `200`이고 이유가 본문에 담겨 있습니다). 공급자 `5xx`, 전송 실패, 콘텐츠 정책 거부, 그리고 Router가 스스로 제기한 모든 거부를 포함한 다른 모든 실패에서는 존재하지 않습니다. 이는 `X-Comfy-Upstream-Detail` 헤더를 반영합니다.
</ResponseField>

<ResponseField name="refusal_subject" type="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` 헤더를 반영합니다.
</ResponseField>

### RouterErrorType

기계가 읽을 수 있는 Router 오류 카테고리로, `X-Comfy-Error-Type` 헤더에도 전송됩니다.

유형: `string`

### RouterModelBilling

모델을 호출하기 전에 확인해야 하는 과금 동작입니다. 가격이나 사용량은 포함하지 않습니다.

**필드**

<ResponseField name="charges_on_policy_rejection" type="RouterChargesOnPolicyRejection" required>
  이 모델이 콘텐츠 정책을 이유로 거부한 호출이 그럼에도 호출자에게 과금되는지 여부입니다. 공급자마다 다르고, 그 차이는 호출 시점에는 보이지 않으며, 같은 호출에 대해 오류와 과금을 함께 보게 된 사용자는 미리 알 방법이 없었습니다. 그래서 공급자마다의 통설에 맡기는 대신, 모델별로 호출 전에 명시합니다.

  타입: [`RouterChargesOnPolicyRejection`](#routerchargesonpolicyrejection)
</ResponseField>

### RouterModelDetail

하나의 Comfy Router 모델에 대한 모델별 상세 정보입니다. 카탈로그 목록이 해당 모델에 대해 보고하는 모든 항목에 더해, 단일 모델 라우트만 제공하는 모델별 필드까지 포함합니다.

[`RouterModelListEntry`](#routermodellistentry), [`RouterModelDetailFields`](#routermodeldetailfields)로 구성됩니다.

타입: `object`

### RouterModelDetailFields

모델 세부 정보 엔드포인트가 반환하는 선택적 필드입니다.

**필드**

<ResponseField name="input_schema_url" type="string">
  이 모델의 OpenAPI 문서 URL이며, 입력 및 출력 스키마를 포함합니다.

  HTTPS URL, 예: `https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json`, 최대 2048자
</ResponseField>

### RouterModelId

`POST /v2/models/{provider}/{model}`에 사용되는 모델 ID입니다.

타입: `string`, 모델 ID, 예: `anthropic/claude-opus-4-6`, 최대 193자

### RouterModelInput

모델 입력 객체입니다. 필드와 검증 정보는 선택한 모델의 OpenAPI 문서를 참고하세요.

타입: `object`

### RouterModelInputSchemaDocument

한 모델의 입력과 출력을 위한 독립형 OpenAPI 문서입니다.

타입: `object`

### RouterModelListEntry

모델의 ID와 청구 정보.

**필드**

<ResponseField name="id" type="RouterModelId" required>
  정식 Comfy Router 모델 ID인 `{provider}/{model}`로, `POST /v2/models/{provider}/{model}`에서 모델을 지정하는 값과 정확히 동일합니다. 따라서 호출자는 다른 곳에서 다시 도출할 필요 없이 이 값을 해당 경로에 그대로 넣을 수 있습니다. `pattern`은 `RouterProviderSegment`와 `RouterModelSegment`를 단일 `/`로 이어 붙인 것이고, `maxLength`는 두 값의 길이 합에 그 구분자를 더한 값입니다.

  타입: [`RouterModelId`](#routermodelid) -- 모델 ID, 예: `anthropic/claude-opus-4-6`, 최대 193자
</ResponseField>

<ResponseField name="provider" type="RouterProviderSegment" required>
  정식 `{provider}/{model}` 모델 ID에서 소문자로 표기되는 `provider` 세그먼트이며, 모델을 지정하는 대상 파트너를 나타냅니다. 호출 라우트의 `provider` 경로 매개변수와 카탈로그 항목의 `provider` 필드가 모두 이 하나의 스키마를 참조하며, 이것이 나열된 ID와 허용되는 ID가 서로 어긋나지 않게 유지합니다.

  타입: [`RouterProviderSegment`](#routerprovidersegment) -- 영숫자 슬러그, 예: `anthropic`, 최대 64자
</ResponseField>

<ResponseField name="model" type="RouterModelSegment" required>
  정식 `{provider}/{model}` 모델 ID에서 소문자로 표기되는 `model` 세그먼트이며, 해당 공급자 안에서 실행할 모델을 나타냅니다. 호출 라우트의 `model` 경로 매개변수와 카탈로그 항목의 `model` 필드에서 공유되며, `RouterProviderSegment`와 마찬가지로 ID가 어긋나지 않게 하기 위한 것입니다.

  타입: [`RouterModelSegment`](#routermodelsegment) -- 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
</ResponseField>

<ResponseField name="billing" type="RouterModelBilling" required>
  호출 전에 호출자가 알아야 하는 모델별 청구 정보이며, 가격이 아닙니다. 사용량과 비용 수치는 여기에 절대 나타나지 않습니다.

  타입: [`RouterModelBilling`](#routermodelbilling)
</ResponseField>

### RouterModelListResponse

Router 모델 카탈로그의 한 페이지입니다.

**필드**

<ResponseField name="data" type="array of RouterModelListEntry" required>
  이 페이지의 모델들로, 최대 `limit`개입니다.

  유형: [`RouterModelListEntry`](#routermodellistentry)의 배열
</ResponseField>

<ResponseField name="has_more" type="boolean" required>
  이 페이지 뒤에 다른 페이지가 있는지 여부입니다. 이 값이 참인 동안 계속 순회하세요. 짧거나 빈 `data`로 카탈로그의 끝이라고 추측하지 마세요.
</ResponseField>

<ResponseField name="next_cursor" type="RouterPageCursor">
  Router 목록에 대한 불투명 커서입니다. 서버에서 생성되며 오직 왕복 전달만 됩니다. 즉, 오프셋도 아니고, 모델 ID도 아니고, 정렬되지 않으며, 카탈로그 재구축 간에 안정적이지 않으므로, 이를 파싱하거나 값을 증가시키거나 그것이 나온 순회를 넘어 보관하는 것은 모두 계약 밖입니다. 오프셋이 아니라 커서인 이유는 카탈로그가 움직이는 목록이기 때문입니다. 오프셋 순회는 순회 도중 항목이 추가되거나 제거되면 조용히 항목을 건너뛰거나 반복하며, 호출자는 그런 일이 발생했는지 알 수 없습니다.

  유형: [`RouterPageCursor`](#routerpagecursor), `next_cursor`로 반환되는 불투명 커서, 1–512자
</ResponseField>

<ResponseField name="limit" type="integer" required>
  실제로 제공된 페이지 크기입니다. 최대값을 초과하여 요청한 `limit`은 거부되지 않고 최대값으로 제한되므로, 이 값은 요청한 값보다 작을 수 있습니다. 보낸 값이 아니라 이 값으로 페이지네이션하세요. 그렇지 않으면 받지도 못한 행을 받았다고 가정하게 됩니다.

  1–100
</ResponseField>

### RouterModelOutput

모델 결과 객체입니다. 정확한 형태를 확인하려면 선택된 모델의 출력 스키마를 참조하세요.

유형: `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 형태를 사용합니다. 두 경우 모두 동일한 진술, 즉 취소가 발견한 내용을 나타내며, 상태 코드마다 다른 타입을 파싱해야 하는 클라이언트는 이러한 분리에서 얻는 것이 없기 때문입니다.

**필드**

<ResponseField name="request_id" type="RouterQueueRequestId" required>
  대기 중인 Router 요청 하나의 식별자입니다. 호출자가 폴링하고 취소하고 결과를 수집할 때 사용하는 핸들입니다.

  타입: [`RouterQueueRequestId`](#routerqueuerequestid) -- `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 최대 36자
</ResponseField>

<ResponseField name="status" type="RouterQueueCancelStatus" required>
  이 라우트가 실제로 처리한 요청을 설명하는 두 결과에 대해, 취소 요청이 발견한 내용입니다. 두 결과 모두 HTTP 상태 코드에 반영되므로, 클라이언트는 둘 중 어느 것으로도 분기할 수 있습니다.

  타입: [`RouterQueueCancelStatus`](#routerqueuecancelstatus)
</ResponseField>

### RouterQueueCancelStatus

취소 요청이 확인한 결과로, 이 라우트가 실제로 처리한 요청을 설명하는 두 가지 결과에 해당합니다. 두 결과 모두 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 블록이 아닌 나머지 절반입니다. 대기 중인 요청 하나의 식별자, 현재 상태, 그리고 그 상태가 터미널이고 실행이 성공하지 못했을 때 그 이유를 나타내는 포괄적 분류입니다.

**필드**

<ResponseField name="request_id" type="RouterQueueRequestId" required>
  대기 중인 Router 요청 하나의 식별자입니다. 호출자가 폴링하고 취소하고 결과를 수집할 때 사용하는 핸들입니다.

  유형: [`RouterQueueRequestId`](#routerqueuerequestid) -- `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 최대 36자
</ResponseField>

<ResponseField name="status" type="RouterQueueStatus" required>
  대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며, `RouterErrorType`과 달리 이것은 닫힌 `enum`입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. `RouterErrorType`은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식할 수 없는 분류를 강하게 거부하는 생성된 클라이언트는 무언가가 이미 잘못된 바로 그 순간에 가장 심하게 실패하게 됩니다. 이 스키마는 라이프사이클이고, 나중에 네 번째 상태가 추가된 라이프사이클은 enum으로 선언되었든 아니든 그에 맞춰 작성된 모든 폴링 루프에 대한 호환성을 깨는 변경입니다. 그래서 enum으로 선언하고, 클라이언트가 볼 수 있는 위치에 제약을 명시합니다.

  유형: [`RouterQueueStatus`](#routerqueuestatus)
</ResponseField>

<ResponseField name="queue_position" type="RouterQueuePosition">
  응답이 구성된 즉시, 실행 대기열에서 이 요청보다 앞에 있는 요청이 몇 개인지입니다. 0은 이 요청이 맨 앞에 있음을 의미합니다.

  유형: [`RouterQueuePosition`](#routerqueueposition) -- 최소 0
</ResponseField>

<ResponseField name="error_type" type="RouterErrorType">
  성공하지 못한 `COMPLETED` 요청에만 존재하며, 결과 조회가 해당 실패를 반환할 때 `X-Comfy-Error-Type`에 붙이는 것과 동일한 포괄적 분류를 담습니다. 성공한 터미널 요청과 실패했거나 취소된 요청을 구분하는 역할을 합니다(둘 모두를 위한 별도의 터미널 상태는 없습니다). 그리고 성공 시에는 null이 아니라 아예 존재하지 않으므로, 존재 여부로 분기하세요.

  유형: [`RouterErrorType`](#routererrortype)
</ResponseField>

### RouterQueueStatusResponse

대기 중인 요청 하나의 현재 상태이며, 제출 시 반환된 것과 동일한 세 개의 URL로 구성됩니다.

[`RouterQueueUrls`](#routerqueueurls), [`RouterQueueStatusFields`](#routerqueuestatusfields)를 구성합니다.

타입: `object`

### RouterQueueSubmitFields

`RouterQueueSubmitResponse`에서 URL 블록이 아닌 나머지 절반: 새 요청의 식별자와 요청이 접수된 순간의 상태입니다.

**필드**

<ResponseField name="request_id" type="RouterQueueRequestId" required>
  대기 중인 Router 요청 하나의 식별자로, 호출자가 폴링하고 취소하고 결과를 수집할 때 사용하는 핸들입니다.

  Type: [`RouterQueueRequestId`](#routerqueuerequestid) -- `pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$`, uuid, 최대 36자
</ResponseField>

<ResponseField name="status" type="RouterQueueStatus" required>
  대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며, `RouterErrorType`과 달리 이쪽은 닫힌 `enum`입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. `RouterErrorType`은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식할 수 없는 분류값을 강하게 거부하는 생성된 클라이언트는 이미 문제가 발생한 바로 그 시점에 가장 심하게 실패하게 됩니다. 이쪽은 라이프사이클이고, 나중에 네 번째 상태가 추가된 라이프사이클은 enum으로 선언되었든 아니든 그에 맞춰 작성된 모든 폴링 루프에 대한 호환성을 깨는 변경입니다. 그래서 enum으로 선언하고, 제약을 클라이언트가 볼 수 있는 곳에 명시합니다.

  Type: [`RouterQueueStatus`](#routerqueuestatus)
</ResponseField>

<ResponseField name="queue_position" type="RouterQueuePosition">
  응답이 구성된 순간에 실행 대기열에서 이 요청보다 앞에 있는 요청의 수입니다. 0이면 이 요청이 맨 앞에 있습니다.

  Type: [`RouterQueuePosition`](#routerqueueposition) -- 최소 0
</ResponseField>

<ResponseField name="estimate" type="RouterCostEstimate">
  이 요청에 대한 사전 비용 추정치로, 호출자에게 비용 추정이 활성화된 경우 새로 접수될 때 포함됩니다. 이 요청이 고정된 공급자 구간을 제시합니다(실행 대기열에는 폴백 루프가 없으므로 `fallback_provider`가 실제로 실행되는 구간을 바꾸는 일은 없습니다). 수치를 제시할 수 없을 때도 `source: unknown`과 함께 여전히 포함되며, 추정치 때문에 제출이 실패하는 일은 없습니다. 멱등 재실행(`Idempotent-Replayed: true`)에서는 원본 견적이 저장되지 않으므로 생략됩니다. 이는 가격 고정이 아닙니다: 실행은 평가될 때 적용되는 요금으로 청구됩니다.

  Type: [`RouterCostEstimate`](#routercostestimate)
</ResponseField>

### RouterQueueSubmitResponse

실행이 실행 대기열에 승인될 때 반환되는 핸들로, 요청의 식별자와 상태에 나머지 수명 주기를 처리하는 세 개의 URL을 결합한 것입니다.

[`RouterQueueUrls`](#routerqueueurls), [`RouterQueueSubmitFields`](#routerqueuesubmitfields)를 구성합니다.

유형: `object`

### RouterQueueUrls

대기 중인 한 요청의 남은 수명을 다루는 세 가지 URL입니다. 활성 핸들을 포함하는 모든 응답에서 반환되므로, 클라이언트가 실행 대기열 URL을 직접 조합할 일이 없습니다.

**필드**

<ResponseField name="status_url" type="string" required>
  이 요청의 상태 조회를 위한 절대 URL입니다.

  URI
</ResponseField>

<ResponseField name="response_url" type="string" required>
  이 요청의 결과를 수집하는 절대 URL입니다.

  URI
</ResponseField>

<ResponseField name="cancel_url" type="string" required>
  취소를 요청하는 절대 URL입니다.

  URI
</ResponseField>

### RouterValidationErrorContext

검증 규칙이 실패한 이유에 대해 공급자가 제공한 세부 정보입니다.

Type: `object`

### RouterValidationErrorDetail

필드 수준 검증 실패 하나입니다.

**필드**

<ResponseField name="loc" type="array of any" required>
  문제가 된 필드의 경로이며, 가장 바깥쪽 세그먼트가 먼저 옵니다. 예를 들어 `["body", "image_url"]`, 또는 정수가 배열의 인덱스를 가리키는 `["body", "images", 0]`과 같습니다.
</ResponseField>

<ResponseField name="msg" type="string" required>
  이 단일 실패에 대한 사람이 읽을 수 있는 설명입니다.
</ResponseField>

<ResponseField name="type" type="string" required>
  이 실패에 대한 구체적이고 기계가 읽을 수 있는 이유이며, 공급자로부터 변경 없이 그대로 전달됩니다. 타입이 지정된 SDK 예외 계층이 분기하는 값이 바로 이것이며, 응답 헤더의 `error_type`은 그것의 포괄적인 분류일 뿐입니다.
</ResponseField>

<ResponseField name="ctx" type="RouterValidationErrorContext">
  하나의 `RouterValidationErrorDetail`에 대해 위반된 경계값으로, 공급자로부터 그대로 전달됩니다. 예를 들어 `greater_than`과 함께 오는 `{"limit_value": 8}`, `image_too_small`과 함께 오는 `{"min_width": 512}`, 또는 `file_too_large`와 함께 오는 `{"max_size_bytes": 10485760}`과 같습니다. 키 집합은 공급자와 오류 유형에 따라 다르므로 이는 의도적으로 열린 객체입니다. 이것을 고정된 필드 목록으로 좁히거나 `msg` 문자열에 접어 넣는 것이야말로, 포팅된 통합이 컴파일은 되지만 경계값을 읽던 분기를 조용히 잃게 되는 바로 그 방식입니다. 오류 유형에 경계값이 없으면 이 필드는 생략됩니다.

  Type: [`RouterValidationErrorContext`](#routervalidationerrorcontext)
</ResponseField>

<ResponseField name="input" type="RouterValidationErrorInput">
  문제가 된 입력 값으로, 호출자가 `loc`에서 다시 도출하지 않고도 무엇이 거부되었는지 볼 수 있도록 그대로 되돌려 전달됩니다. 문자열, 숫자, 논리값, 배열, 객체 또는 null 등 모든 JSON 타입이므로, 이 스키마는 객체로 좁히지 않고 의도적으로 타입 없이 둡니다. 공급자가 입력을 되돌려 전달하지 않으면 이 필드는 생략됩니다.

  Type: [`RouterValidationErrorInput`](#routervalidationerrorinput)
</ResponseField>

### RouterValidationErrorInput

거부된 입력 값이며, 공급자가 이를 포함하는 경우에 해당합니다.

### RouterValidationErrorResponse

`422` 검증 오류 본문입니다. 카테고리는 `X-Comfy-Error-Type`을 확인하세요.

**필드**

<ResponseField name="detail" type="array of RouterValidationErrorDetail" required>
  요청에서 발견된 모든 검증 실패 항목으로, 문제가 있는 필드마다 하나의 항목이 대응합니다.

  유형: [`RouterValidationErrorDetail`](#routervalidationerrordetail)의 배열
</ResponseField>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.