Comfy Router API 레퍼런스

Comfy Router의 정식 라우트로, 모델 ID로 주소가 지정됩니다. 기본 URL: https://api.comfy.org 아래의 모든 엔드포인트에는 인증이 필요합니다. Authorization: Bearer <jwt>를 전송하십시오.

Endpoints

`GET /v1/models`

List the models Comfy Router can run. Comfy Router’s model catalog - one page of the canonical model IDs that POST /v1/models/{provider}/{model} accepts. An SDK calls this on cold start to discover what is runnable, and the model_not_found suggestions come from the same catalog, so an ID listed here that then 404s on invocation would be worse than either failure alone. That agreement is structural rather than a promise: an entry’s provider and model are the two path segments of the invocation route and reference the SAME schema components that route’s path parameters do, and id is those two segments joined by /. Parameters

Name	In	Required	Type	Constraints	Description
`cursor`	query	no	`RouterPageCursor`	`pattern: ^[A-Za-z0-9._~+/=-]+$`, `minLength: 1`, `maxLength: 512`	Opaque pagination cursor. Pass a previous page’s `next_cursor` to fetch the next page; omit it for the first page. See `RouterPageCursor` for why the value is opaque and why this route paginates by cursor rather than by offset.
`limit`	query	no	integer	`maximum: 100`, `default: 20`	Number of models to return in one page. Values above the declared maximum are outside the contract, but this route does not reject them: it serves the maximum instead, and the page size actually served is echoed back as `limit` on the response, so a clamp is always detectable by the caller. Treat the maximum as the real page stride - a client that asks for more and assumes it received more will miss rows. 0 and negative values are also accepted and select the default, which is why no `minimum` is declared: sub-1 is meaningful here, not invalid.

Responses

Status	Body	Headers	Description
`200`	`RouterModelListResponse`	`X-Comfy-Request-Id`	OK - one page of the model catalog.
`400`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.
`401`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.

`GET /v1/models/{provider}/{model}`

Read one partner model’s catalog entry by canonical model ID. Per-model detail for a single Comfy Router model, so a caller can check one model without walking the whole paginated catalog. The SDKs use it to look a model up immediately before invoking it. Parameters

Name	In	Required	Type	Constraints	Description
`provider`	path	yes	`RouterProviderSegment`	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64`	Lowercase provider segment of the canonical `{provider}/{model}[/{variant}]` model ID - the partner whose model is being run.
`model`	path	yes	`RouterModelSegment`	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128`	Lowercase model segment of the canonical `{provider}/{model}[/{variant}]` model ID - the model to run within that provider.

Responses

Status	Body	Headers	Description
`200`	`RouterModelDetail`	`X-Comfy-Request-Id`	OK - the model’s catalog entry.
`404`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.

`POST /v1/models/{provider}/{model}`

Run a partner model synchronously by canonical model ID. Comfy Router’s canonical, model-ID-addressed entry point. The request body is the partner model’s OWN native JSON input and the success response is that model’s OWN native JSON output: Router forwards both unchanged instead of imposing a Comfy-shaped envelope, so a caller can move between the partner’s API and Router by changing the host. This is the SYNCHRONOUS path, mirroring POST https://fal.run/{id} - the response carries the finished result. A queued counterpart, /v1/queue/models/{provider}/{model}, is planned and would put fal’s fal.run / queue.fal.run split onto a single host; it is not part of this contract yet. Parameters

Name	In	Required	Type	Constraints	Description
`provider`	path	yes	`RouterProviderSegment`	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64`	Lowercase provider segment of the canonical `{provider}/{model}[/{variant}]` model ID - the partner whose model is being run.
`model`	path	yes	`RouterModelSegment`	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128`	Lowercase model segment of the canonical `{provider}/{model}[/{variant}]` model ID - the model to run within that provider.

Request body application/json — RouterModelInput (required) The partner model’s native JSON input, forwarded to the provider unchanged. Responses

Status	Body	Headers	Description
`200`	`RouterModelOutput`	`X-Comfy-Request-Id`	OK - the partner model’s native JSON output, returned unchanged.
`403`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.
`404`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.
`422`	`RouterValidationErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	The request reached the model and the model rejected its contents. The body is `RouterValidationErrorResponse`, the fal/FastAPI `detail[]` shape, so each offending field keeps its own specific `type` and `ctx`. `X-Comfy-Error-Type` carries the coarse bucket for the whole response.
`503`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.
`504`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.

`GET /v1/models/{provider}/{model}/openapi.json`

Read one partner model’s input schema as an OpenAPI document. The per-model input schema for a single Comfy Router model, served as a standalone OpenAPI document, so a caller - an SDK, a codegen tool, or an agent - can discover a model’s arguments without reading Comfy’s prose docs. It mirrors fal’s per-model schema endpoint, and it is the discovery mechanism the SDK quickstart depends on. Parameters

Name	In	Required	Type	Constraints	Description
`provider`	path	yes	`RouterProviderSegment`	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64`	Lowercase provider segment of the canonical `{provider}/{model}[/{variant}]` model ID - the partner whose model is being run.
`model`	path	yes	`RouterModelSegment`	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128`	Lowercase model segment of the canonical `{provider}/{model}[/{variant}]` model ID - the model to run within that provider.

Responses

Status	Body	Headers	Description
`200`	`RouterModelInputSchemaDocument`	`X-Comfy-Request-Id`, `ETag`, `Cache-Control`	OK - the model’s input schema, as a standalone OpenAPI document.
`304`	-	`X-Comfy-Request-Id`, `ETag`, `Cache-Control`	Not Modified - the document is unchanged since the `ETag` the caller sent in `If-None-Match`. No body is returned.
`404`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `X-Comfy-Error-Type`.
`500`	`RouterErrorResponse`	`X-Comfy-Error-Type`, `X-Comfy-Request-Id`	A Router request-level failure - the request never reached the model, or failed for a reason the model itself did not report. The body is `RouterErrorResponse` and the bucket is repeated on `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.
`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`를 받을 수 있습니다.
`X-Comfy-Error-Type`	`RouterErrorType`	Router가 모든 오류 응답에 설정하는, 오류에 대한 대략적인 기계 판독 가능 버킷입니다. `RouterErrorResponse.error_type`과 동일한 값을 가지며, `422`에서는 이것이 유일한 기계 판독 가능 버킷입니다. 해당 본문이 fal/FastAPI `detail[]` 형태이고 자체 `error_type` 필드가 없기 때문입니다. 따라서 클라이언트는 수신한 두 Router 오류 본문 중 어느 것인지 결정하기 이전에 이 헤더만으로 분기할 수 있습니다.
`X-Comfy-Request-Id`	문자열	이 호출에 대해 서버에서 생성된 식별자로, 모든 Router 응답(성공, 4xx, 5xx 모두)에 존재합니다. 오류 응답이 바로 사용자가 지원 요청에 인용할 id가 필요한 때이기 때문입니다. 동일한 값이 호출의 사용량/감사 이벤트에 기록되므로, 요금에 대한 불만을 타임스탬프로 검색하는 대신 요금 자체에 연결할 수 있습니다.

모델별 입력 스키마

모델의 자체 입력 필드는 여기에 다시 수록하지 않습니다. 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`	예	-	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`	예	-	이 모델이 콘텐츠 정책에 따라 거부한 호출에 대해서도 호출자에게 청구되는지 여부입니다. 공급자마다 다르며, 그 차이는 호출 시간에 확인할 수 없습니다. 같은 호출에 대해 오류와 청구를 모두 확인한 사용자는 이를 알 방법이 없으므로, 공급자별 관례에 맡기는 대신 호출 이전에 모델별로 명시됩니다.	### RouterModelDetail

Comfy Router 모델 하나에 대한 모델별 세부 정보: 카탈로그 목록이 해당 모델에 대해 보고하는 모든 정보와, 단일 모델 라우트에서만 제공되는 모델별 필드를 포함합니다. RouterModelListEntry와 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`	예	`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`	예	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 64`	정규 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 `provider` 세그먼트입니다. 모델이 주소 지정되는 파트너를 나타냅니다. 호출 라우트의 `provider` 경로 매개변수와 카탈로그 항목의 `provider` 필드는 모두 이 하나의 스키마를 참조하므로, 목록의 ID와 허용되는 ID가 서로 어긋나지 않습니다.
`model`	`RouterModelSegment`	예	`pattern: ^[a-z0-9]+([._-][a-z0-9]+)*$`, `maxLength: 128`	정규 `{provider}/{model}[/{variant}]` 모델 ID의 소문자 `model` 세그먼트입니다. 해당 공급자 내에서 실행할 모델을 나타냅니다. 호출 라우트의 `model` 경로 매개변수와 카탈로그 항목의 `model` 필드는 `RouterProviderSegment`와 동일한 불일치 방지 이유로 이 스키마를 공유합니다.
`billing`	`RouterModelBilling`	예	-	호출자가 호출 이전에 알아야 하는 모델별 청구 정보입니다. 가격이 아닙니다. 사용량 및 비용 수치는 여기에 절대 나타나지 않습니다.	### RouterModelListResponse

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

필드	유형	필수	제약 조건	설명
`data`	`RouterModelListEntry`의 배열	예	-	이 페이지에 포함된 모델로, 최대 `limit`개입니다.
`has_more`	논리값	예	-	이 페이지 이후에 다른 페이지가 더 존재하는지 여부입니다. 이 값이 참인 동안 계속 탐색하십시오. `data`가 짧거나 비어 있더라도 카탈로그의 끝으로 유추하지 마십시오.
`next_cursor`	`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 fal/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`	아니요	-	하나의 `RouterValidationErrorDetail`에 대해 위반된 제약 조건으로, 공급자로부터 그대로 전달됩니다. 예를 들어 `greater_than`과 함께 `{"limit_value": 8}`, `image_too_small`과 함께 `{"min_width": 512}`, 또는 `file_too_large`와 함께 `{"max_size_bytes": 10485760}`이 있습니다. 키 집합은 공급자와 오류 유형에 따라 다르므로 의도적으로 개방형 객체(open object)로 남겨 둡니다. 이를 고정된 필드 목록으로 좁히거나 `msg` 문자열에 통합하면, 이식된 통합이 컴파일은 성공하지만 제약 조건을 읽는 분기를 조용히 잃어버리게 됩니다. 오류 유형에 제약 조건이 없는 경우에는 이 필드가 없습니다.
`input`	`RouterValidationErrorInput`	아니요	-	문제가 되는 입력 값으로, 호출자가 `loc`에서 다시 도출하지 않고 무엇이 거부되었는지 확인할 수 있도록 있는 그대로 다시 전달됩니다. 모든 JSON 유형(문자열, 숫자, 논리값, 배열, 객체 또는 null)이 가능하므로 이 스키마는 객체로 좁히지 않고 의도적으로 유형을 지정하지 않은 상태로 둡니다. 공급자가 입력을 다시 전달하지 않는 경우에는 이 필드가 없습니다.	### RouterValidationErrorInput

문제가 되는 입력 값으로, 호출자가 loc에서 다시 도출하지 않고도 거부된 값이 무엇인지 확인할 수 있도록 있는 그대로 반환됩니다. 문자열, 숫자, 논리값, 배열, 객체 또는 null 등 모든 JSON 유형이 될 수 있으므로, 이 스키마는 객체로 한정하지 않고 의도적으로 유형을 지정하지 않은 채로 둡니다. 공급자가 입력을 다시 반환하지 않는 경우에는 이 필드가 존재하지 않습니다.### RouterValidationErrorResponse Router의 모델 수준 422 본문으로, fal/FastAPI 형식입니다. 요청이 모델에 도달할 수 있을 만큼 형식이 올바르게 갖추어졌지만, 모델이 그 내용을 거부했음을 의미합니다. 자체적으로 error_type을 포함하지 않는다는 점에 유의하세요. 그 역할은 응답의 X-Comfy-Error-Type이 담당하므로, 클라이언트는 수신한 두 가지 Router 오류 본문 중 어떤 것인지 먼저 판단하지 않고도 헤더에서 대략적인 분류를 읽을 수 있습니다.

필드	유형	필수	제약 조건	설명
`detail`	`RouterValidationErrorDetail`의 배열	예	-	요청에서 발견된 모든 검증 실패로, 문제가 있는 필드당 하나의 항목입니다.

Comfy로 개발하기

워크플로 실행

Comfy Router

Comfy CLI

스펙

Comfy Router API 레퍼런스

Endpoints

`GET /v1/models`

`GET /v1/models/{provider}/{model}`

`POST /v1/models/{provider}/{model}`

`GET /v1/models/{provider}/{model}/openapi.json`

Error buckets

Request-level buckets

Transport-level buckets

응답 헤더

모델별 입력 스키마

스키마

RouterChargesOnPolicyRejection

​Endpoints

​GET /v1/models

​GET /v1/models/{provider}/{model}

​POST /v1/models/{provider}/{model}

​GET /v1/models/{provider}/{model}/openapi.json

​Error buckets

​Request-level buckets

​Transport-level buckets

​응답 헤더

​모델별 입력 스키마

​스키마

​RouterChargesOnPolicyRejection

Endpoints

`GET /v1/models`

`GET /v1/models/{provider}/{model}`

`POST /v1/models/{provider}/{model}`

`GET /v1/models/{provider}/{model}/openapi.json`

Error buckets

Request-level buckets

Transport-level buckets

응답 헤더

모델별 입력 스키마

스키마

RouterChargesOnPolicyRejection