> ## Documentation Index > Fetch the complete documentation index at: https://dripart-docs-comfy-router-docs.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # Comfy Router API 레퍼런스 > Comfy API 계약에서 생성된 모든 Comfy Router 엔드포인트, 매개변수, 응답 본문 및 오류 버킷. Comfy Router의 정식 라우트로, 모델 ID로 주소가 지정됩니다. 기본 URL: `https://api.comfy.org` 아래의 모든 엔드포인트에는 인증이 필요합니다. `Authorization: Bearer `를 전송하십시오. ## 엔드포인트 ### `GET /v1/models` **Comfy Router가 실행할 수 있는 모델을 나열합니다.** Comfy Router의 모델 카탈로그 - `POST /v1/models/{provider}/{model}`가 허용하는 표준 모델 ID의 한 페이지입니다. SDK는 콜드 스타트 시 이 엔드포인트를 호출하여 실행 가능한 모델을 발견하며, `model_not_found` 제안도 동일한 카탈로그에서 제공됩니다. 따라서 여기에 나열된 ID가 호출 시 404를 반환한다면 어느 한쪽만 실패하는 것보다 더 나쁩니다. 이러한 일관성은 약속이 아니라 구조적인 것입니다. 항목의 `provider`와 `model`은 호출 경로의 두 경로 세그먼트이며 해당 경로의 경로 파라미터가 참조하는 동일한 스키마 구성 요소를 참조하고, `id`는 이 두 세그먼트를 `/`로 연결한 것입니다. **파라미터** | 이름 | 위치 | 필수 | 유형 | 제약 조건 | 설명 | | -------- | ----- | --- | --------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `cursor` | query | 아니요 | [`RouterPageCursor`](#routerpagecursor) | `pattern: ^[A-Za-z0-9._~+/=-]+$`, `minLength: 1`, `maxLength: 512` | 불투명한 페이지네이션 커서입니다. 이전 페이지의 `next_cursor`를 전달하면 다음 페이지를 가져오고, 첫 페이지에서는 생략합니다. 값이 불투명한 이유와 이 경로가 offset 대신 커서로 페이지네이션하는 이유는 `RouterPageCursor`를 참조하세요. | | `limit` | query | 아니요 | integer | `maximum: 100`, `default: 20` | 한 페이지에 반환할 모델 수입니다. 선언된 최대값을 초과하는 값은 계약 범위를 벗어나지만, 이 경로는 해당 값을 거부하지 않습니다. 대신 최대값을 제공하며, 실제 제공된 페이지 크기는 응답의 `limit`으로 그대로 반환됩니다. 따라서 상한 적용 여부는 호출자가 항상 감지할 수 있습니다. 최대값을 실제 페이지 간격으로 취급하세요. 더 많이 요청하고 더 많이 받았다고 가정하는 클라이언트는 행을 놓칠 수 있습니다. 0과 음수 값도 허용되며 기본값을 선택합니다. 이것이 `minimum`이 선언되지 않은 이유입니다. 1 미만은 여기서 유효하지 않은 것이 아니라 의미 있는 값입니다. | **응답** | 상태 | 본문 | 헤더 | 설명 | | ----- | ----------------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------- | | `200` | [`RouterModelListResponse`](#routermodellistresponse) | `X-Comfy-Request-Id` | OK - 모델 카탈로그의 한 페이지입니다. | | `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패: 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type`에 반복됩니다. | | `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패: 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type`에 반복됩니다. | | `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패: 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type`에 반복됩니다. | | `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패: 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type`에 반복됩니다. | ### `GET /v1/models/{provider}/{model}` **정규 모델 ID로 파트너 모델 하나의 카탈로그 항목을 조회합니다.** 단일 Comfy Router 모델에 대한 모델별 세부 정보로, 호출자가 전체 페이지네이션 카탈로그를 일일이 탐색하지 않고도 모델 하나를 확인할 수 있습니다. SDK는 모델을 호출하기 직전에 이 엔드포인트를 사용하여 모델을 조회합니다. **파라미터** | 이름 | 위치 | 필수 | 유형 | 제약 조건 | 설명 | | ---------- | ---- | -- | ------------------------------------------------- | --------------------------------------------------------- | ----------------------------------------------------------------------------- | | `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64` | 정규 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 공급자 세그먼트: 모델이 실행되는 파트너입니다. | | `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128` | 정규 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 모델 세그먼트: 해당 공급자 내에서 실행할 모델입니다. | **응답** | 상태 | 본문 | 헤더 | 설명 | | ----- | --------------------------------------------- | ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | | `200` | [`RouterModelDetail`](#routermodeldetail) | `X-Comfy-Request-Id` | OK: 모델의 카탈로그 항목입니다. | | `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 라우터 요청 수준의 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에도 동일하게 포함됩니다. | | `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 라우터 요청 수준의 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에도 동일하게 포함됩니다. | | `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 라우터 요청 수준의 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에도 동일하게 포함됩니다. | ### `POST /v1/models/{provider}/{model}` **표준 모델 ID로 파트너 모델을 동기식으로 실행합니다.** Comfy Router의 표준 진입점으로, 모델 ID로 주소가 지정됩니다. 요청 본문은 파트너 모델 자체의 네이티브 JSON 입력이고, 성공 응답은 해당 모델 자체의 네이티브 JSON 출력입니다. Router는 Comfy 형태의 래퍼를 강제하는 대신 둘 다 변경 없이 그대로 전달하므로, 호출자는 호스트만 변경하여 파트너 API와 Router 사이를 이동할 수 있습니다. 이 경로는 동기(SYNCHRONOUS) 경로입니다. 응답에는 완료된 결과가 포함됩니다. **파라미터** | 이름 | 위치 | 필수 | 유형 | 제약 조건 | 설명 | | ---------- | ---- | --- | ------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------ | | `provider` | path | yes | [`RouterProviderSegment`](#routerprovidersegment) | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64` | 표준 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 공급자 세그먼트입니다. 실행할 모델을 보유한 파트너를 나타냅니다. | | `model` | path | yes | [`RouterModelSegment`](#routermodelsegment) | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128` | 표준 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 모델 세그먼트입니다. 해당 공급자 내에서 실행할 모델을 나타냅니다. | **요청 본문** `application/json` -- [`RouterModelInput`](#routermodelinput) (필수) 파트너 모델의 네이티브 JSON 입력으로, 변경 없이 공급자에게 전달됩니다. **응답** | 상태 | 본문 | 헤더 | 설명 | | ----- | ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `200` | [`RouterModelOutput`](#routermodeloutput) | `X-Comfy-Request-Id` | OK: 파트너 모델의 네이티브 JSON 출력이 변경 없이 반환됩니다. | | `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에 동일하게 표시됩니다. | | `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에 동일하게 표시됩니다. | | `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 요청이 모델에 도달했지만 모델이 내용을 거부했습니다. 본문은 FastAPI `detail[]` 형태의 `RouterValidationErrorResponse`이므로, 각 오류 필드는 고유한 `type`과 `ctx`를 유지합니다. `X-Comfy-Error-Type`은 전체 응답에 대한 포괄적인 버킷을 전달합니다. | | `429` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining` | 호출자가 허용된 진행 중 용량을 모두 점유하고 있어 요청이 모델에 도달하기 전에 거부되었습니다. 어느 경우든 버킷은 `concurrency_limit_exceeded`이며, `detail`이 어떤 한도에 걸렸는지 알려줍니다. 동시 호출 수이거나, 아직 진행 중인 호출의 확정 지출(committed spend)이며, 후자에 의한 거부에는 `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining` 헤더(미국 달러 센트 단위)도 함께 담깁니다. 호출자 자신의 진행 중인 호출 중 하나가 끝나면 재시도하세요. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에 동일하게 표시됩니다. | | `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 보고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며, 버킷은 `X-Comfy-Error-Type` 헤더에 동일하게 표시됩니다. | | `504` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` | Comfy가 자체 구성된 한계에서 연결 유지를 중단했습니다(`deadline_exceeded`). 본문과 두 헤더는 `RouterRequestError`의 것과 정확히 같으며, 여기에 추가되는 것은 선택적 `Retry-After`입니다. 같은 `Idempotency-Key`로 재시도하면 새 생성을 보내는 대신 아직 실행 중인 생성을 회수하게 되는 경우에 포함됩니다. `POST /v1/models/{provider}/{model}`의 `504`를 참조하세요. | ### `GET /v1/models/{provider}/{model}/openapi.json` **파트너 모델 하나의 입력 스키마를 OpenAPI 문서로 읽습니다.** 단일 Comfy Router 모델의 모델별 입력 스키마를 독립형 OpenAPI 문서로 제공합니다. 이를 통해 호출자(SDK, 코드 생성 도구 또는 에이전트)는 Comfy의 문서를 읽지 않고도 모델의 인자를 발견할 수 있습니다. 이는 SDK 퀵스타트가 의존하는 발견 메커니즘입니다. **파라미터** | 이름 | 위치 | 필수 | 유형 | 제약 조건 | 설명 | | --------------- | ------ | --- | ------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `provider` | path | yes | [`RouterProviderSegment`](#routerprovidersegment) | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64` | 표준 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 공급자 세그먼트로, 실행 중인 모델의 파트너를 식별합니다. | | `model` | path | yes | [`RouterModelSegment`](#routermodelsegment) | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128` | 표준 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델을 식별합니다. | | `If-None-Match` | header | no | string | - | 호출자가 이전 `200`에서 보관해 둔 `ETag`입니다. 현재 문서와 일치하면(RFC 9110 약한 비교, `*`는 현재의 어떤 문서와도 일치) 같은 `ETag`를 담은 본문 없는 `304`가 응답되고, 그렇지 않으면 전체 문서가 반환됩니다. | **응답** | 상태 | 본문 | 헤더 | 설명 | | ----- | ------------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | `200` | [`RouterModelInputSchemaDocument`](#routermodelinputschemadocument) | `X-Comfy-Request-Id`, `ETag`, `Cache-Control` | OK: 모델의 입력 스키마를 독립형 OpenAPI 문서로 반환합니다. | | `304` | - | `X-Comfy-Request-Id`, `ETag`, `Cache-Control` | Not Modified: 호출자가 `If-None-Match`에 보낸 `ETag` 이후로 문서가 변경되지 않았습니다. 본문은 반환되지 않습니다. | | `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며 버킷은 `X-Comfy-Error-Type` 헤더에도 반복 표시됩니다. | | `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며 버킷은 `X-Comfy-Error-Type` 헤더에도 반복 표시됩니다. | | `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며 버킷은 `X-Comfy-Error-Type` 헤더에도 반복 표시됩니다. | | `500` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며 버킷은 `X-Comfy-Error-Type` 헤더에도 반복 표시됩니다. | | `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준 실패입니다. 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유로 실패했습니다. 본문은 `RouterErrorResponse`이며 버킷은 `X-Comfy-Error-Type` 헤더에도 반복 표시됩니다. | ## Error buckets Coarse, machine-readable bucket for a Router failure, mirrored on the `X-Comfy-Error-Type` response header so a caller can branch without parsing the body. The set is closed at fifteen values: the six request-level buckets `invalid_input`, `content_policy_violation`, `provider_error`, `provider_timeout`, `insufficient_credits` and `model_not_found`, plus the transport-level `unauthorized`, `forbidden`, `concurrency_limit_exceeded`, `client_disconnected`, `internal_error`, `deadline_exceeded`, `not_enabled`, `service_unavailable` and `rate_limited`. ### Request-level buckets Raised for a request Router accepted and then could not complete. | `error_type` | Meaning | | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `invalid_input` | The request was rejected before it reached the model - a malformed body, a malformed or expired pagination cursor, or an input the model's own schema does not accept. | | `content_policy_violation` | The provider refused the request on content-policy grounds. The refusal is deterministic: re-sending the same input will be refused again. | | `provider_error` | The partner provider reported a failure of its own, or returned a response Router could not interpret as a result. | | `provider_timeout` | The partner provider did not answer within its deadline. This bucket is the PROVIDER timing out and never Router's own server deadline, which is reported as `deadline_exceeded` - the two share `504` and are separated because they name different causes: this one says the partner failed, that one says Comfy stopped holding the connection. | | `insufficient_credits` | The calling workspace does not have enough credits to run the model. | | `model_not_found` | The `{provider}/{model}` ID names no model Router can run; an unknown provider lands here too. `detail` carries up to three suggestions drawn from the models the caller is entitled to see. | ### Transport-level buckets Raised by Router itself, before or around the call to the model. | `error_type` | Meaning | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `unauthorized` | The request carried no usable credential. | | `forbidden` | The credential is valid but is not entitled to this model or this operation. | | `concurrency_limit_exceeded` | The workspace already has as many calls in flight as it is allowed; retry once one of them finishes. | | `client_disconnected` | The caller closed the connection before Router could return a result. It is logged rather than delivered - there is no socket left to write it to - and it is an attribution, not a billing outcome: a provider generation that completed is billed regardless of whether the caller received the response. | | `internal_error` | Router itself failed. It is also the value a client should treat any UNRECOGNIZED bucket as, so a later addition to the set does not break a client generated before it. | | `deadline_exceeded` | Comfy stopped holding the connection at its own configured bound before an answer arrived. It shares `504` with `provider_timeout` and the pair says which side ran out of time; this one is Comfy's own bound, so nothing about the request was rejected and the same request may be retried. It says nothing about the charge: a provider generation that completed is billed regardless of whether the caller received the response. Retry it with the SAME `Idempotency-Key`: when the provider had already accepted the generation, the retry collects that generation rather than dispatching another, and a `Retry-After` on the `504` says when to ask. | | `not_enabled` | Comfy Router is not switched on for this caller yet. Nothing about the request is wrong and the model exists, which is why this is not `model_not_found`; it shares `403` with `forbidden` and is NOT the same thing, because `forbidden` is an entitlement decision about the caller while this is a state of the rollout. It is TERMINAL: do not retry, and do not treat it as an outage. | | `service_unavailable` | A service Comfy Router depends on is temporarily unavailable and the caller did nothing wrong. Retry it with backoff: it is the one bucket here whose condition clears on its own, without the caller changing the request and without a concurrency slot freeing, which is what distinguishes it from the other retryable answers (`concurrency_limit_exceeded`, `deadline_exceeded`). It is separate from `internal_error` - which is a `500` and means Router itself failed - so a client can tell "come back shortly" from "this call is not going to work". | | `rate_limited` | The caller has spent an allowance measured over a WINDOW and must wait for that window to roll. It shares `429` with `concurrency_limit_exceeded` and is not the same thing: that one clears the moment one of the caller's own in-flight calls finishes, so retrying in seconds is right, whereas nothing the caller does drains this one early. `detail` names the window. | ## 응답 헤더 | 헤더 | 유형 | 설명 | | ----------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Cache-Control` | 문자열 | 제공되는 스키마 문서에 대한 신선도 지시문입니다. `private`은 경로가 인증되어 있기 때문입니다. 문서 자체는 호출자별로 다르지 않지만, 공유 캐시는 인증된 요청에 대한 응답을 보유해서는 안 됩니다. `must-revalidate`는 오래된 복사본이 그대로 제공되는 대신 `ETag`에 대해 재검증되도록 하기 위함입니다. | | `ETag` | 문자열 | `GET /v1/models/{provider}/{model}/openapi.json`에 대해 제공되는 문서 바이트에 대한 강력한 엔티티 태그입니다. 모델별 스키마는 거의 변경되지 않지만 SDK가 자주 다시 가져오므로, 호출자는 이 값을 저장한 뒤 `If-None-Match`로 다시 보내 문서 대신 `304`를 받을 수 있습니다. | | `Retry-After` | 정수 | 같은 `Idempotency-Key`로 같은 요청을 재시도하기 전에 기다려야 할 초 수입니다. `deadline_exceeded` `504`에서 공급자가 아직 실행 중인 생성에 대한 핸들을 Comfy가 보유한 경우에만 존재합니다. 값은 Router 자체의 폴링 간격으로, 이 경로가 "나중에 다시 물어보라"에 대해 제시할 수 있는 유일하게 정직한 숫자입니다. 회수할 것이 없을 때, 즉 키 없는 호출이거나 공급자가 무엇이든 수락하기 전에 한계가 만료된 경우에는 존재하지 않습니다. | | `X-Comfy-Error-Type` | [`RouterErrorType`](#routererrortype) | Router가 모든 오류 응답에 설정하는, 오류에 대한 대략적인 기계 판독 가능 버킷입니다. `RouterErrorResponse.error_type`과 동일한 값을 가지며, `422`에서는 이것이 유일한 기계 판독 가능 버킷입니다. 해당 본문이 FastAPI `detail[]` 형태이고 자체 `error_type` 필드가 없기 때문입니다. 따라서 클라이언트는 수신한 두 Router 오류 본문 중 어느 것인지 결정하기 이전에 이 헤더만으로 분기할 수 있습니다. | | `X-Comfy-Request-Id` | 문자열 | 이 호출에 대해 서버에서 생성된 식별자로, 모든 Router 응답(성공, 4xx, 5xx 모두)에 존재합니다. 오류 응답이 바로 사용자가 지원 요청에 인용할 id가 필요한 때이기 때문입니다. 동일한 값이 호출의 사용량/감사 이벤트에 기록되므로, 요금에 대한 불만을 타임스탬프로 검색하는 대신 요금 자체에 연결할 수 있습니다. | | `X-Committed-Spend-Current` | 정수 | 호출자가 현재 진행 중인 호출에 확정한 금액(미국 달러 센트)으로, 거부된 호출은 포함하지 않습니다. `X-Committed-Spend-Limit`과 함께 존재합니다. | | `X-Committed-Spend-Limit` | 정수 | 호출자가 진행 중인 호출에 확정할 수 있는 파트너 지출의 상한(미국 달러 센트)입니다. 거부 사유가 동시 호출 풀이 아니라 확정 지출 상한이었을 때 존재합니다. | | `X-Committed-Spend-Remaining` | 정수 | 상한 아래 남은 여유분(미국 달러 센트)으로, 최소값은 0입니다. 거부 시에도 양수일 수 있습니다. 거부된 호출의 비용이 남은 금액보다 컸을 뿐이며, 더 저렴한 호출은 여전히 허용됩니다. `X-Committed-Spend-Limit`과 함께 존재합니다. | ## 모델별 입력 스키마 모델의 자체 입력 필드는 여기에 다시 수록하지 않습니다. `GET /v1/models/{provider}/{model}/openapi.json`에서 실시간으로 확인하세요. 이 엔드포인트는 서버가 호출을 검증할 때 사용하는 문서와 동일한 문서를 제공하므로, 게시된 내용과 실제로 강제 적용되는 내용이 서로 어긋날 수 없습니다. `GET /v1/models`에서 모델 ID를 가져와 해당 호출 경로에 `/openapi.json`을 추가하고, 반환된 문서를 기준으로 생성을 진행하세요. ## 스키마 ### RouterChargesOnPolicyRejection 이 모델이 콘텐츠 정책을 근거로 거부하는 호출이 그럼에도 불구하고 호출자에게 청구되는지 여부를 나타냅니다. 공급자마다 다르며, 그 차이는 호출 시점에 드러나지 않습니다. 동일한 호출에 대해 오류와 청구를 함께 확인한 사용자는 이를 알 도리가 없습니다. 따라서 이는 공급자별 구전 지식에 맡겨지지 않고, 호출 이전에 모델별로 명시됩니다. 타입: `string` ### RouterErrorResponse Router의 요청 수준 오류 본문: 요청이 모델에 도달하지 못했거나, 모델 자체가 신고하지 않은 이유(인증, 할당량, 알 수 없는 모델 ID, 공급자 전송)로 실패한 경우 반환되는 내용입니다. 모델 수준 검증 실패는 `RouterValidationErrorResponse`라는 자체 형태를 가집니다. FastAPI의 `detail[]` 배열을 이 `detail` 문자열로 평탄화하면 SDK가 분기하는 필드별 세분성이 손상되기 때문입니다. | 필드 | 유형 | 필수 | 제약 조건 | 설명 | | ------------ | ------------------------------------- | -- | ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `detail` | string | 예 | - | 실패에 대한 사람이 읽을 수 있는 설명으로, 최종 사용자에게 표시해도 안전합니다. 기계가 파싱하지 않으므로 대신 `error_type`으로 분기하세요. | | `error_type` | [`RouterErrorType`](#routererrortype) | 예 | - | Router 실패에 대한 대략적이고 기계가 읽을 수 있는 분류로, `X-Comfy-Error-Type` 응답 헤더에도 동일하게 반영되므로 호출자가 본문을 파싱하지 않고 분기할 수 있습니다. 값 집합은 15개로 고정되어 있습니다. 여섯 가지 요청 수준 분류인 `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`가 있습니다. | ### RouterErrorType Router 오류를 대략적이고 기계가 읽을 수 있는 버킷으로 분류한 것으로, `X-Comfy-Error-Type` 응답 헤더에도 반영되므로 호출자가 본문을 파싱하지 않고도 분기할 수 있습니다. 이 집합은 15개의 값으로 고정되어 있습니다: 요청 수준의 6개 버킷인 `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`입니다. 유형: `string` ### RouterModelBilling 모델별 청구에 관한 사실은 호출자가 호출 이전에 알아야 할 내용으로, 가격이 아닙니다. 사용량 및 비용 수치는 여기에 표시되지 않습니다. | 필드 | 유형 | 필수 | 제약 조건 | 설명 | | ----------------------------- | ------------------------------------------------------------------- | -- | ----- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `charges_on_policy_rejection` | [`RouterChargesOnPolicyRejection`](#routerchargesonpolicyrejection) | 예 | - | 이 모델이 콘텐츠 정책에 따라 거부한 호출에 대해서도 호출자에게 청구되는지 여부입니다. 공급자마다 다르며, 그 차이는 호출 시간에 확인할 수 없습니다. 같은 호출에 대해 오류와 청구를 모두 확인한 사용자는 이를 알 방법이 없으므로, 공급자별 관례에 맡기는 대신 호출 이전에 모델별로 명시됩니다. | ### RouterModelDetail Comfy Router 모델 하나에 대한 모델별 세부 정보: 카탈로그 목록이 해당 모델에 대해 보고하는 모든 정보와, 단일 모델 라우트에서만 제공되는 모델별 필드를 포함합니다. [`RouterModelListEntry`](#routermodellistentry)와 [`RouterModelDetailFields`](#routermodeldetailfields)로 구성됩니다. 유형: `object` ### RouterModelDetailFields `RouterModelDetail` 중 카탈로그 목록이 담지 않는 절반: 한 번의 조회로 충분하지만 페이지네이션된 카탈로그 페이지의 모든 항목에 반복할 가치가 없는 모델별 필드입니다. | 필드 | 타입 | 필수 | 제약 조건 | 설명 | | ------------------ | --- | --- | ------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `input_schema_url` | 문자열 | 아니요 | `format: uri`, `pattern: ^https://`, `maxLength: 2048` | 이 모델의 입력 스키마 문서를 가리키는 포인터입니다. 입력 스키마 문서는 이 모델에 대해 `POST /v1/models/{provider}/{model}`이 받아들이는 본문(body)의 설명입니다. 오직 포인터만이 이 계약의 일부입니다. 포인터가 가리키는 문서는 별도로 작성됩니다. 모델에 대한 스키마가 작성되지 않은 경우에는 이 필드가 존재하지 않습니다. | ### RouterModelId `{provider}/{model}` 형식의 표준 Comfy Router 모델 ID입니다. 이 값은 `POST /v1/models/{provider}/{model}`에서 모델을 주소 지정하는 값과 정확히 일치하므로, 호출자는 다른 곳에서 다시 파생할 필요 없이 해당 경로에 바로 삽입할 수 있습니다. `pattern`은 단일 `/`로 연결된 `RouterProviderSegment`와 `RouterModelSegment`이며, `maxLength`는 두 값의 합에 해당 구분자를 더한 값입니다. 유형: `string`. `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*/[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 193` ### RouterModelInput 파트너 모델의 네이티브 JSON 입력 문서로, 공급자에게 있는 그대로 전달됩니다. 구체적인 형태는 Comfy가 아닌 파트너가 소유하므로 이는 개방형 객체입니다. Router는 필드의 범위를 좁히거나 이름을 바꾸거나 다시 감싸지 않습니다. ComfyUI의 스펙 기반 코드 생성이 생성할 클래스를 필요로 하기 때문에 명명된 컴포넌트입니다(인라인 익명 객체는 절대 아님). 유형: `object` ### RouterModelInputSchemaDocument 단일 Comfy Router 모델의 입력을 설명하는 독립 OpenAPI 문서로, 해당 모델에 대해 `POST /v1/models/{provider}/{model}`가 허용하는 요청 본문입니다. `GET /v1/models/{provider}/{model}/openapi.json`이 반환하는 내용이기도 합니다. 유형: `object` ### RouterModelListEntry Router 모델 카탈로그의 한 항목입니다. 실행 가능한 모델의 식별 정보만을 담으며, 그 외의 다른 것은 포함하지 않습니다. 모델별 상세 라우트는 이 동일한 항목을 반복해서 기술하는 대신 이 항목을 조합하여 사용합니다. 따라서 이름이 `...Summary`가 아니라 `...ListEntry`인 이유는, 카탈로그 항목이 무엇인지에 대한 정의가 정확히 하나만 존재해야 하기 때문입니다. 모델별 상세 및 모델별 입력/출력 스키마는 각각 별도의 라우트이므로, 이 형태는 호출자가 모델을 호출하는 데 필요한 최소한의 정보로 유지됩니다. 이는 의도적인 설계입니다. SDK가 콜드 스타트 시 가져오는 페이로드가 바로 이것이기 때문입니다. `id`는 `provider`와 `model`을 `/`로 연결한 값입니다. 두 필드는 별도로도 제공되므로 호출자는 문자열을 분할하지 않고 호출 경로를 구성할 수 있습니다. | 필드 | 타입 | 필수 | 제약 조건 | 설명 | | ---------- | ------------------------------------------------- | -- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | [`RouterModelId`](#routermodelid) | 예 | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*/[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 193` | 정규 Comfy Router 모델 ID인 `{provider}/{model}`입니다. `POST /v1/models/{provider}/{model}`에서 모델을 주소 지정하는 값과 정확히 일치하므로, 호출자는 다른 어떤 값에서도 다시 파생할 필요 없이 해당 경로에 그대로 삽입할 수 있습니다. 이 `pattern`은 `RouterProviderSegment`와 `RouterModelSegment`를 단일 `/`로 연결한 것이며, `maxLength`는 두 값의 합에 해당 구분자를 더한 값입니다. | | `provider` | [`RouterProviderSegment`](#routerprovidersegment) | 예 | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64` | 정규 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 `provider` 세그먼트입니다. 모델이 주소 지정되는 파트너를 나타냅니다. 호출 라우트의 `provider` 경로 매개변수와 카탈로그 항목의 `provider` 필드는 모두 이 하나의 스키마를 참조하므로, 목록의 ID와 허용되는 ID가 서로 어긋나지 않습니다. | | `model` | [`RouterModelSegment`](#routermodelsegment) | 예 | `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128` | 정규 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 `model` 세그먼트입니다. 해당 공급자 내에서 실행할 모델을 나타냅니다. 호출 라우트의 `model` 경로 매개변수와 카탈로그 항목의 `model` 필드는 `RouterProviderSegment`와 동일한 불일치 방지 이유로 이 스키마를 공유합니다. | | `billing` | [`RouterModelBilling`](#routermodelbilling) | 예 | - | 호출자가 호출 이전에 알아야 하는 모델별 청구 정보입니다. 가격이 아닙니다. 사용량 및 비용 수치는 여기에 절대 나타나지 않습니다. | ### RouterModelListResponse Router 모델 카탈로그의 한 페이지입니다. | 필드 | 유형 | 필수 | 제약 조건 | 설명 | | ------------- | --------------------------------------------------- | --- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `data` | [`RouterModelListEntry`](#routermodellistentry)의 배열 | 예 | - | 이 페이지에 포함된 모델로, 최대 `limit`개입니다. | | `has_more` | 논리값 | 예 | - | 이 페이지 이후에 다른 페이지가 더 존재하는지 여부입니다. 이 값이 참인 동안 계속 탐색하십시오. `data`가 짧거나 비어 있더라도 카탈로그의 끝으로 유추하지 마십시오. | | `next_cursor` | [`RouterPageCursor`](#routerpagecursor) | 아니요 | `pattern: ^[A-Za-z0-9._~+/=-]+$`, `minLength: 1`, `maxLength: 512` | Router 목록에 대한 불투명(opaque) 커서입니다. 서버가 생성하며 클라이언트에 전달되었다가 그대로 반환될 뿐입니다. 오프셋도 아니고, 모델 ID도 아니며, 정렬되지 않고, 카탈로그가 다시 구축될 때에도 안정적이지 않습니다. 따라서 이 커서를 구문 분석하거나, 증가시키거나, 커서가 나온 탐색 범위를 넘어 보존하는 것은 모두 계약 범위 밖입니다. 오프셋 대신 커서를 사용하는 이유는 카탈로그가 계속 변하는 목록이기 때문입니다. 탐색 중간에 항목이 추가되거나 제거되면 오프셋 기반 탐색은 항목을 조용히 건너뛰거나 반복하게 되며, 호출자는 그 사실을 알 수 없습니다. | | `limit` | 정수 | 예 | `minimum: 1`, `maximum: 100` | 실제로 제공된 페이지 크기입니다. 최대값을 초과하는 `limit` 요청은 거부되지 않고 최대값으로 제한(clamp)됩니다. 따라서 이 값은 요청한 값보다 작을 수 있습니다. 페이지네이션에는 보낸 값이 아닌 이 값을 사용하십시오. 그렇지 않으면 실제로 수신하지 못한 행이 있다고 가정하게 됩니다. | ### RouterModelOutput 파트너 모델의 네이티브 JSON 출력 문서로, 호출자에게 있는 그대로 반환됩니다. 구체적인 형태는 Comfy가 아닌 파트너가 소유하므로, 이는 개방형 객체(open object)입니다. Router는 필드를 좁히거나, 이름을 바꾸거나, 다시 래핑하지 않습니다. ComfyUI의 스펙 기반 코드 생성(codegen)에는 생성할 클래스가 필요하기 때문에, 이는 named 컴포넌트입니다(인라인 익명 객체가 아닙니다). 유형: `object` ### RouterModelSegment 표준 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 `model` 세그먼트: 해당 공급자 내에서 실행할 모델입니다. `RouterProviderSegment`와 동일한 드리프트 방지 이유로 호출 라우트의 `model` 경로 파라미터와 카탈로그 항목의 `model` 필드에서 공유됩니다. 타입: `string`. `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128` ### RouterPageCursor Router 목록에 대한 OPAQUE 커서입니다. 서버에 의해 생성되며 항상 왕복 전송만 됩니다. 즉, 오프셋도, 모델 ID도, 정렬된 값도 아니며, 카탈로그 재구축 시에도 안정적이지 않습니다. 따라서 커서를 파싱하거나 증가시키거나, 커서가 생성된 탐색(walk) 범위를 벗어나 보관하는 것은 모두 계약 범위 밖입니다. 오프셋 대신 커서를 사용하는 이유는 카탈로그가 계속 변하는 목록이기 때문입니다. 오프셋 탐색은 탐색 중 항목이 추가되거나 제거되면 항목을 소리 없이 건너뛰거나 반복하게 되며, 호출자는 그런 일이 발생했는지 알 수 없습니다. Type: `string` -- `pattern: ^[A-Za-z0-9._~+/=-]+$`, `minLength: 1`, `maxLength: 512` ### RouterProviderSegment 정규 `{provider}/{model}[/{variant}]` 모델 ID에서 소문자 `provider` 세그먼트로, 요청 대상 모델의 파트너를 나타냅니다. 호출 라우트의 `provider` 경로 매개변수와 카탈로그 항목의 `provider` 필드는 모두 이 하나의 스키마를 참조하므로, 나열된 ID와 허용되는 ID가 서로 어긋나지 않게 유지됩니다. 유형: `string` - `pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64` ### RouterValidationErrorContext 하나의 `RouterValidationErrorDetail`에 대해 위반된 한도이며, 공급자로부터 그대로 전달됩니다. 예를 들어 `greater_than`과 함께 `{"limit_value": 8}`, `image_too_small`과 함께 `{"min_width": 512}`, 또는 `file_too_large`와 함께 `{"max_size_bytes": 10485760}`이 이에 해당합니다. 키 집합은 공급자와 오류 유형에 따라 달라지므로, 이 객체는 의도적으로 열린 객체입니다. 이를 고정된 필드 목록으로 좁히거나 `msg` 문자열로 접으면, 포팅된 통합이 컴파일은 되지만 한도를 읽던 분기를 조용히 잃어버리는 결과를 낳습니다. 오류 유형에 한도가 없는 경우에는 이 값이 없습니다. 유형: `object` ### RouterValidationErrorDetail FastAPI 형식의 모델 수준 검증 오류 하나입니다. `type`은 특정 공급자 사유(`value_error`, `missing`, `image_too_small`, `unsupported_audio_format`, `greater_than`, `file_too_large` 등)를 담으며, 이는 `RouterErrorType`의 대략적인 분류가 표현할 수 없는 세부 수준입니다. 같은 이유로 이 값은 `enum`이 아닌 개방형 문자열(open string)입니다. 공급자 어휘는 두 계층에 걸쳐 약 48개 값에 달하며, 우리가 아니라 공급자의 릴리스 주기에 따라 늘어납니다. 따라서 모델링되지 않은 값은 역직렬화에 실패하기보다 호출자에게 도달해야 합니다. | 필드 | 유형 | 필수 | 제약 조건 | 설명 | | ------- | --------------------------------------------------------------- | --- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `loc` | 모든 유형의 배열 | 예 | - | 문제가 되는 필드의 경로로, 가장 바깥쪽 세그먼트가 먼저 옵니다. 예를 들어 `["body", "image_url"]` 또는 `["body", "images", 0]`이며, 여기서 정수는 배열의 인덱스를 나타냅니다. | | `msg` | 문자열 | 예 | - | 이 단일 실패에 대한 사람이 읽을 수 있는 설명입니다. | | `type` | 문자열 | 예 | - | 이 실패에 대한 구체적이고 기계가 읽을 수 있는 사유로, 공급자로부터 변경 없이 그대로 전달됩니다. 타입이 지정된 SDK 예외 계층 구조가 분기하는 기준이 되는 값이며, 응답 헤더의 `error_type`은 그 대략적인 분류일 뿐입니다. | | `ctx` | [`RouterValidationErrorContext`](#routervalidationerrorcontext) | 아니요 | - | 하나의 `RouterValidationErrorDetail`에 대해 위반된 제약 조건으로, 공급자로부터 그대로 전달됩니다. 예를 들어 `greater_than`과 함께 `{"limit_value": 8}`, `image_too_small`과 함께 `{"min_width": 512}`, 또는 `file_too_large`와 함께 `{"max_size_bytes": 10485760}`이 있습니다. 키 집합은 공급자와 오류 유형에 따라 다르므로 의도적으로 개방형 객체(open object)로 남겨 둡니다. 이를 고정된 필드 목록으로 좁히거나 `msg` 문자열에 통합하면, 이식된 통합이 컴파일은 성공하지만 제약 조건을 읽는 분기를 조용히 잃어버리게 됩니다. 오류 유형에 제약 조건이 없는 경우에는 이 필드가 없습니다. | | `input` | [`RouterValidationErrorInput`](#routervalidationerrorinput) | 아니요 | - | 문제가 되는 입력 값으로, 호출자가 `loc`에서 다시 도출하지 않고 무엇이 거부되었는지 확인할 수 있도록 있는 그대로 다시 전달됩니다. 모든 JSON 유형(문자열, 숫자, 논리값, 배열, 객체 또는 null)이 가능하므로 이 스키마는 객체로 좁히지 않고 의도적으로 유형을 지정하지 않은 상태로 둡니다. 공급자가 입력을 다시 전달하지 않는 경우에는 이 필드가 없습니다. | ### RouterValidationErrorInput 문제가 되는 입력 값으로, 호출자가 `loc`에서 다시 도출하지 않고도 거부된 값이 무엇인지 확인할 수 있도록 있는 그대로 반환됩니다. 문자열, 숫자, 논리값, 배열, 객체 또는 null 등 모든 JSON 유형이 될 수 있으므로, 이 스키마는 객체로 한정하지 않고 의도적으로 유형을 지정하지 않은 채로 둡니다. 공급자가 입력을 다시 반환하지 않는 경우에는 이 필드가 존재하지 않습니다. ### RouterValidationErrorResponse Router의 모델 수준 `422` 본문으로, FastAPI 형식입니다. 요청이 모델에 도달할 수 있을 만큼 형식이 올바르게 갖추어졌지만, 모델이 그 내용을 거부했음을 의미합니다. 자체적으로 `error_type`을 포함하지 않는다는 점에 유의하세요. 그 역할은 응답의 `X-Comfy-Error-Type`이 담당하므로, 클라이언트는 수신한 두 가지 Router 오류 본문 중 어떤 것인지 먼저 판단하지 않고도 헤더에서 대략적인 분류를 읽을 수 있습니다. | 필드 | 유형 | 필수 | 제약 조건 | 설명 | | -------- | ----------------------------------------------------------------- | -- | ----- | ----------------------------------------- | | `detail` | [`RouterValidationErrorDetail`](#routervalidationerrordetail)의 배열 | 예 | - | 요청에서 발견된 모든 검증 실패로, 문제가 있는 필드당 하나의 항목입니다. |