> ## Documentation Index
> Fetch the complete documentation index at: https://dripart-comfy-docs-comfyapi-search.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`
아래의 모든 엔드포인트에는 인증이 필요합니다. `X-API-Key: ` 또는 `Authorization: Bearer `를 전송하십시오.
Comfy API 키는 Bearer 토큰으로도 전송할 수 있습니다. 두 자격 증명 헤더를 모두 제공하면 `X-API-Key`가 우선합니다. 키와 JWT의 구분은 [인증 헤더](/ko/development/comfy-router/quickstart)를, 액세스 요구 사항은 [퀵스타트](/ko/development/comfy-router/quickstart)를 참고하십시오.
## 엔드포인트
### `GET /v2/models`
**Comfy Router가 실행할 수 있는 모델 목록을 조회합니다.**
사용 가능한 모델 ID와 과금 정보를 나열합니다. `has_more`가 참인 동안 `next_cursor`를 사용하세요.
**파라미터**
| 이름 | 위치 | 필수 | 유형 | 제약 조건 | 설명 |
| -------- | ----- | --- | --------------------------------------- | ---------------------------------- | ---------------- |
| `cursor` | query | 아니요 | [`RouterPageCursor`](#routerpagecursor) | `next_cursor`로 반환되는 불투명 커서, 1–512자 | 불투명 페이지네이션 커서. |
| `limit` | query | 아니요 | integer | 최대 100, 기본값: 20 | 한 페이지에 반환할 모델 수. |
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| ----- | ----------------------------------------------------- | ------------------------------------------ | ----------------------------------------- |
| `200` | [`RouterModelListResponse`](#routermodellistresponse) | `X-Comfy-Request-Id` | OK - 모델 카탈로그의 한 페이지입니다. |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요. |
### `GET /v2/models/{provider}/{model}`
**정식 모델 ID로 파트너 모델 하나의 카탈로그 항목을 조회합니다.**
전체 카탈로그를 나열하지 않고 하나의 모델에 대한 세부 정보를 조회합니다.
**파라미터**
| 이름 | In | 필수 | 유형 | 제약 조건 | 설명 |
| ---------- | ---- | -- | ------------------------------------------------- | -------------------------------------- | ----------------------------------------- |
| `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 정식 `{provider}/{model}` 모델 ID의 공급자 부분입니다. |
| `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 정식 `{provider}/{model}` 모델 ID의 모델 부분입니다. |
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| ----- | --------------------------------------------- | ------------------------------------------ | ------------------------------------------- |
| `200` | [`RouterModelDetail`](#routermodeldetail) | `X-Comfy-Request-Id` | OK - 모델의 카탈로그 항목입니다. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 사용하여 재시도하세요. |
### `POST /v2/models/{provider}/{model}`
**정식 모델 ID로 파트너 모델을 동기식으로 실행합니다.**
모델을 실행하고 완료된 결과를 동일한 응답으로 받습니다.
**파라미터**
| 이름 | 위치 | 필수 | 유형 | 제약 | 설명 |
| ----------------- | ------ | --- | ------------------------------------------------- | -------------------------------------- | ----------------------------------------- |
| `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 정식 `{provider}/{model}` 모델 ID의 공급자 부분입니다. |
| `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 정식 `{provider}/{model}` 모델 ID의 모델 부분입니다. |
| `Idempotency-Key` | header | 아니요 | 문자열 | 1\~255자 | 하나의 논리적 호출을 재시도해도 안전하게 만드는 호출자 생성 키입니다. |
**요청 본문**
`application/json` -- [`RouterModelInput`](#routermodelinput) (필수)
파트너 모델의 네이티브 JSON 입력으로, 변경 없이 공급자에게 전달됩니다.
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| ----- | ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | [`RouterModelOutput`](#routermodeloutput) | `X-Comfy-Request-Id`, `X-Content-Type-Options`, `Idempotent-Replayed`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining` | OK: 파트너 모델의 네이티브 출력이 파트너 자체의 미디어 타입으로 변경 없이 반환됩니다. |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`, `Idempotent-Replayed` | 잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `409` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` (`concurrency_limit_exceeded`인 경우) | `X-Comfy-Error-Type`을 확인하세요. `concurrency_limit_exceeded`는 원본 호출이 아직 실행 중이라는 뜻이므로 `Retry-After`만큼 기다린 뒤 동일한 키를 재사용하세요. `invalid_input`은 새 키가 필요합니다. |
| `413` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 요청 본문이 너무 큽니다. |
| `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed` | 요청 내용이 모델의 스키마에 맞지 않아 거부되었습니다. |
| `429` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Committed-Spend-Limit`, `X-Committed-Spend-Current`, `X-Committed-Spend-Remaining` | `X-Comfy-Error-Type`을 확인하세요. `concurrency_limit_exceeded`는 진행 중인 호출을 줄이라는 뜻이고, `rate_limited`는 허용량 창(window)을 기다리라는 뜻입니다. |
| `502` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status` | 공급자의 응답을 결과로 변환할 수 없습니다(`provider_error`). |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요. |
| `504` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `X-Comfy-Upstream-Status`, `Retry-After` | 요청이 기한을 초과했습니다. 재시도하기 전에 오류 유형을 확인하세요. |
### `GET /v2/models/{provider}/{model}/openapi.json`
**하나의 파트너 모델의 입력 및 출력 스키마를 OpenAPI 문서로 읽습니다.**
하나의 모델의 입력 및 출력 스키마를 독립 실행형 OpenAPI 문서로 읽습니다.
**파라미터**
| 이름 | 위치 | 필수 | 유형 | 제약 조건 | 설명 |
| --------------- | ------ | --- | ------------------------------------------------- | -------------------------------------- | ----------------------------------------- |
| `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 표준 `{provider}/{model}` 모델 ID의 공급자 부분입니다. |
| `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 표준 `{provider}/{model}` 모델 ID의 모델 부분입니다. |
| `If-None-Match` | header | 아니요 | 문자열 | - | 이전 `200` 응답에서 호출자가 보유한 `ETag`입니다. |
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| ----- | ------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------- |
| `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` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `500` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router가 요청을 완료할 수 없습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 사용하여 재시도하세요. |
### `POST /v2/models/{provider}/{model}/requests`
**파트너 모델 실행을 실행 대기열에 제출하고 즉시 반환합니다.**
Comfy Router의 QUEUED 전달 모드입니다. 요청 본문은 이 모델에 대해 `POST /v2/models/{provider}/{model}`이 허용하는 것과 동일한 파트너 네이티브 JSON 입력입니다. 즉 본문 형태는 하나, 모델별 스키마도 하나이고 전달 모드만 두 가지인데, 이 경로는 결과를 위해 연결을 유지하지 않습니다. 실행을 접수하고 핸들과 함께 `201`로 응답하며, 호출자는 아래 세 가지 읽기 작업을 통해 나중에 결과를 수집합니다.
**파라미터**
| 이름 | 위치 | 필수 | 유형 | 제약 | 설명 |
| ----------------- | ------ | --- | ------------------------------------------------- | -------------------------------------- | -------------------------------------------------------------------- |
| `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트입니다. 모델이 실행되는 파트너입니다. |
| `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트입니다. 해당 공급자 내에서 실행할 모델입니다. |
| `Idempotency-Key` | header | 아니요 | 문자열 | 1–255자 | 하나의 논리적 호출을 재시도해도 안전하게 만들어 주는, 호출자가 생성한 키입니다. |
**요청 본문**
`application/json` -- [`RouterModelInput`](#routermodelinput) (필수)
파트너 모델의 네이티브 JSON 입력으로, 이 모델에 대해 동기 경로가 허용하는 본문과 동일합니다. 실행이 접수되기 이전에 모델 자체의 입력 스키마에 대해 검증되므로, 모델이 거부할 본문은 몇 분 뒤에 실패하는 대기 중 요청이 아니라 여기서 `422`가 됩니다.
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| ----- | ----------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `201` | [`RouterQueueSubmitResponse`](#routerqueuesubmitresponse) | `X-Comfy-Request-Id`, `Idempotent-Replayed` | 생성됨. 실행이 실행 대기열에 접수되었습니다. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 유효하지 않은 요청입니다. 오류 유형과 요청 본문을 확인하세요. |
| `413` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 요청 본문이 너무 큽니다. |
| `402` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패입니다. 요청이 모델에 도달하지 않았거나, 모델 자체가 보고하지 않은 이유로 실패했습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해 허용되지 않는 요청입니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `409` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Retry-After` (`concurrency_limit_exceeded`인 경우) | `X-Comfy-Error-Type`을 확인하세요. `concurrency_limit_exceeded`는 원본 호출이 아직 실행 중이라는 뜻이므로 `Retry-After`만큼 기다린 후 동일한 키를 재사용하세요. `invalid_input`은 새 키가 필요합니다. |
| `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed` | 요청의 내용이 모델의 스키마에 대해 거부되었습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요. |
### `GET /v2/models/{provider}/{model}/requests/{request_id}`
**제출된 요청 하나의 결과를 수집합니다.**
수집 엔드포인트입니다. 성공적으로 완료된 요청에 대해서는 파트너 모델 자체의 네이티브 출력을 반환합니다. 이는 동일한 모델과 동일한 입력에 대해 동기 라우트의 `200`이 전달하는 것과 바이트 단위로 정확히 같습니다. 따라서 두 전달 방식은 하나의 결과 형태를 만들어내며, 호출자는 별도의 파서 없이 두 방식 사이를 오갈 수 있습니다.
**파라미터**
| 이름 | 위치 | 필수 | 타입 | 제약 | 설명 |
| ------------ | -- | -- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `provider` | 경로 | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 slug, 예: `anthropic`, 최대 64자 | 정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트로, 모델이 실행되는 파트너를 나타냅니다. |
| `model` | 경로 | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 slug, 예: `claude-opus-4-6`, 최대 128자 | 정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델을 나타냅니다. |
| `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자 | 처리할 대기 중 요청으로, 제출 시 반환된 `request_id`이며 해당 제출의 `X-Comfy-Request-Id` 헤더가 담고 있던 값이기도 합니다. |
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| --------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | [`RouterModelOutput`](#routermodeloutput) | `X-Comfy-Request-Id`, `X-Content-Type-Options` | OK - 결과를 생성한 요청에 대한 파트너 모델의 네이티브 출력입니다. 성공적으로 완료된 요청, 또는 기록된 과금과 저장된 결과를 모두 가진 터미널 요청을 의미하며, 파트너 자체의 미디어 타입으로 변경 없이 반환되며, 동기 라우트의 `200`이 반환하는 방식과 정확히 같습니다. |
| `202` | [`RouterQueueStatusResponse`](#routerqueuestatusresponse) | `X-Comfy-Request-Id`, `Retry-After` | 수락됨 - 요청이 아직 완료되지 않았습니다. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해 요청이 허용되지 않습니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `410` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패로, 요청이 모델에 도달하지 않았거나 모델 자체가 보고하지 않은 이유로 실패했습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하십시오. |
| `409` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 요청이 해당 작업과 충돌하는 상태에 있습니다. 오류 타입을 확인하십시오. |
| `504` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 요청이 마감 시간을 초과했습니다. 재시도하기 전에 오류 타입을 확인하십시오. |
| `422` | [`RouterValidationErrorResponse`](#routervalidationerrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id`, `Idempotent-Replayed` | 요청의 콘텐츠가 모델의 스키마에 대해 거부되었습니다. |
| `default` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패로, 요청이 모델에 도달하지 않았거나 모델 자체가 보고하지 않은 이유로 실패했습니다. |
### `PUT /v2/models/{provider}/{model}/requests/{request_id}/cancel`
**제출된 요청 하나의 취소를 요청합니다.**
아직 완료되지 않은 요청을 중지하도록 Comfy에 요청합니다. 이는 요청일 뿐 보장이 아니며, `202`는 바로 그것을 의미합니다: `CANCELLATION_REQUESTED`는 요청이 접수되었다는 뜻이지 실행이 중지되었다는 뜻이 아닙니다. 파트너에서 이미 전송 중인 실행은 그대로 완료될 수 있고, 완료된 파트너 생성은 누군가 결과를 수집했는지 여부와 관계없이 과금됩니다. 따라서 실제로 무슨 일이 일어났는지 알아야 하는 호출자는 이후 상태 엔드포인트를 조회해야 하며, 여기서 효력이 발생한 취소는 다른 모든 터미널 결과와 마찬가지로 `error_type`을 포함한 `COMPLETED`로 나타납니다.
**파라미터**
| 이름 | 위치 | 필수 | 유형 | 제약 | 설명 |
| ------------ | ---- | -- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트로, 모델이 실행되는 파트너입니다. |
| `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다. |
| `request_id` | path | 예 | [`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자 | 처리할 대기 중 요청입니다. 제출 시 반환된 `request_id`이며, 해당 제출의 `X-Comfy-Request-Id` 헤더가 담고 있던 값이기도 합니다. |
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| --------- | --------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
| `202` | [`RouterQueueCancelResponse`](#routerqueuecancelresponse) | `X-Comfy-Request-Id` | 수락됨: `CANCELLATION_REQUESTED`. |
| `409` | [`RouterQueueCancelResponse`](#routerqueuecancelresponse) | `X-Comfy-Request-Id` | 충돌: `ALREADY_COMPLETED`. |
| `400` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 잘못된 요청입니다. 오류 유형과 요청 본문을 확인하세요. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해서는 요청이 허용되지 않습니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 두고 재시도하세요. |
| `default` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패로, 요청이 모델에 도달하지 않았거나 모델 자체가 보고하지 않은 이유로 실패했습니다. |
### `GET /v2/models/{provider}/{model}/requests/{request_id}/status`
**제출된 요청 하나의 실행 대기열 상태를 조회합니다.**
폴링 엔드포인트입니다. 요청의 현재 상태만 응답하고 결과는 응답하지 않으므로, 클라이언트는 매 폴링마다 출력을 전송받지 않고도 오래 걸리는 생성을 지켜볼 수 있습니다. 결과는 이 응답이 `COMPLETED`를 반환할 때 아래의 조회를 통해 한 번만 수집됩니다.
**파라미터**
| 이름 | 위치 | 필수 | 타입 | 제약 | 설명 |
| ------------ | ---- | -- | ------------------------------------------------- | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- |
| `provider` | path | 예 | [`RouterProviderSegment`](#routerprovidersegment) | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 정규 `{provider}/{model}` 모델 ID의 소문자 공급자 세그먼트로, 실행할 모델을 제공하는 파트너입니다. |
| `model` | path | 예 | [`RouterModelSegment`](#routermodelsegment) | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 정규 `{provider}/{model}` 모델 ID의 소문자 모델 세그먼트로, 해당 공급자 내에서 실행할 모델입니다. |
| `request_id` | path | 예 | [`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자 | 처리할 대기 중 요청으로, 제출 시 반환된 `request_id`이며 해당 제출의 `X-Comfy-Request-Id` 헤더에 담긴 값이기도 합니다. |
**응답**
| 상태 | 본문 | 헤더 | 설명 |
| --------- | --------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------- |
| `200` | [`RouterQueueStatusResponse`](#routerqueuestatusresponse) | `X-Comfy-Request-Id`, `Retry-After` | OK: 요청의 현재 실행 대기열 상태입니다. |
| `401` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 자격 증명이 누락되었거나 유효하지 않습니다. |
| `403` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 이 호출자 또는 모델에 대해 요청이 허용되지 않습니다. |
| `404` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | 모델 ID를 찾을 수 없습니다. |
| `410` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패로, 요청이 모델에 도달하지 못했거나 모델 자체가 보고하지 않은 이유로 실패했습니다. |
| `503` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router를 일시적으로 사용할 수 없습니다. 백오프를 적용해 재시도하세요. |
| `default` | [`RouterErrorResponse`](#routererrorresponse) | `X-Comfy-Error-Type`, `X-Comfy-Request-Id` | Router 요청 수준의 실패로, 요청이 모델에 도달하지 못했거나 모델 자체가 보고하지 않은 이유로 실패했습니다. |
표의 설명은 간략합니다. 모델 선택, 검증, 재시도, 과금에 대해서는 [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가 실행할 수 있는 모델을 가리키지 않습니다. 알 수 없는 공급자도 여기에 해당합니다. |
### 전송 수준 분류
모델 호출 이전이나 그 무렵에 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` | 호출자가 WINDOW를 기준으로 측정되는 허용량을 모두 소진했으며, 해당 창이 넘어갈 때까지 기다려야 합니다. |
| `cancelled` | 대기 중이던 요청이 결과를 생성하기 전에 취소 경로를 통해서든 운영자에 의해서든 철회되었습니다. 이는 터미널 상태이며, 그 자체로 요금 청구에 대한 진술은 아닙니다. |
| `queue_timeout` | 대기 중인 요청이 실행 대기열 타임아웃을 넘겨 대기했지만 결국 승인되지 않았습니다. |
| `request_not_found` | `request_id`가 이 모델에서 호출자의 요청 중 어느 것도 가리키지 않습니다. |
## 응답 헤더
| 헤더 | 유형 | 설명 |
| ----------------------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `Cache-Control` | 문자열 | 제공되는 스키마 문서에 대한 신선도 지시문입니다. |
| `ETag` | 문자열 | `GET /v2/models/{provider}/{model}/openapi.json`에 대해 제공되는 문서 바이트에 대한 강력한 엔티티 태그입니다. |
| `Idempotent-Replayed` | 논리값 | 이 응답이 모델을 다시 실행한 것이 아니라 `Idempotency-Key`의 기록에서 제공된 경우 존재하며 `true`입니다. |
| `Retry-After` | 정수 | 동일한 `Idempotency-Key`로 동일한 요청을 재시도하기 전에 기다려야 할 초 수입니다. |
| `X-Comfy-Error-Type` | [`RouterErrorType`](#routererrortype) | 실패에 대한 대략적인 기계 판독 가능 버킷으로, Router가 모든 오류 응답에 설정합니다. |
| `X-Comfy-Request-Id` | 문자열 | 이 호출에 대해 서버가 생성한 식별자로, 모든 Router 응답(성공, 4xx, 5xx 모두)에 존재합니다. 오류 응답이 바로 사용자가 지원팀 요청에 인용할 id가 필요한 때이기 때문입니다. |
| `X-Comfy-Upstream-Status` | 정수 | 이 호출에 대한 모델 공급자 자체의 HTTP 상태입니다. |
| `X-Committed-Spend-Current` | 정수 | 호출자가 현재 진행 중인 호출에 확정한 미국 달러 센트 금액입니다. |
| `X-Committed-Spend-Limit` | 정수 | 호출자가 진행 중인 호출에 확정할 수 있는 파트너 지출의 상한(미국 달러 센트)입니다. 호출이 허용되는 시점부터 금액이 보류되고 해당 호출이 끝나면 해제됩니다. |
| `X-Committed-Spend-Remaining` | 정수 | 상한 아래에 남은 여유분(미국 달러 센트)으로, 최소값은 0입니다. |
| `X-Content-Type-Options` | 문자열 | Router 모델의 모든 성공 실행에서 항상 `nosniff`입니다. |
## 결과 에셋
모델은 에셋 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 비디오 행에 포함되지 않습니다.
**Veo(`veo/*`)는 별도의 스토리지 경로를 사용합니다.** `response.videos[]`에서 존재하는 멤버를 읽으세요. `bytesBase64Encoded`는 클립을 인라인으로 담고 있으며, `gcsUri`는 환경이 공급자의 Comfy 스토리지 직접 쓰기에 맞게 구성된 경우 Comfy가 서명한 HTTPS 링크를 담고 있습니다. 해당 링크는 응답 시점부터 24시간 동안 유효합니다. 후자의 경우 에셋을 복사하는 대신 직접 쓰기 때문에 Veo는 재호스팅 표에 포함되지 않습니다.
다른 모델은 공급자 에셋 참조 또는 인라인 바이트를 반환합니다. 공급자 URL은 공급자의 만료 정책을 따르며, 이는 위 수명보다 훨씬 짧을 수 있고 Router 계약에 명시되어 있지 않습니다.
복사는 에셋별 최선 노력 방식으로 수행됩니다. 복사 하나가 실패하면 해당 항목은 공급자 참조를 유지합니다. 응답에는 Comfy URL과 공급자 URL이 모두 포함될 수 있으며, 에셋별 복사 상태 필드는 명시적으로 없습니다. 생성은 여전히 성공하며 과금됩니다. 성공적으로 재호스팅된 에셋 하나로 모든 URL의 수명을 추론하지 마세요.
결과가 Comfy 호스팅인지 여부는 완료된 호출을 나중에 해당 `Idempotency-Key` 레코드에서 재생할 수 있는지도 결정합니다. 위의 `Idempotency-Key` 매개변수는 재생할 수 없을 때 재시도에 무엇이 응답되는지 설명합니다.
## 모델별 입력 및 출력 스키마
각 모델의 필드는 `GET /v2/models/{provider}/{model}/openapi.json`에서 확인할 수 있습니다. 오퍼레이션의 `requestBody`는 입력 검증을 설명하고, `200` 응답은 스키마가 작성된 경우 출력 형태와 미디어 타입을 설명합니다. `x-comfy-input-schema-authored`가 거짓이면 Router는 모델별 사전 검증 없이 모든 JSON 객체를 허용합니다. 공급자 요구 사항은 여전히 적용됩니다. 출력 스키마는 결과를 설명하는 것이며, Router가 반환된 공급자 페이로드를 스키마와 대조하여 검증하지는 않습니다. 스키마가 작성되지 않은 출력은 `application/json` 대신 `*/*`를 사용할 수 있으므로, 디코딩하기 전에 응답 콘텐츠 타입을 확인하세요.
## 스키마
### RouterChargesOnPolicyRejection
이 모델에 대해 콘텐츠 정책 거부가 과금되는지 여부입니다. 알 수 없는 값은 과금될 수 있는 것으로 간주하세요.
타입: `string`
### RouterErrorResponse
인증, 접근, 모델 조회, 할당량 및 공급자 전송 실패에 대한 오류 본문입니다.
| 필드 | 타입 | 필수 | 제약 조건 | 설명 |
| ------------ | ------------------------------------- | -- | ----- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detail` | 문자열 | 예 | - | 최종 사용자에게 노출해도 안전한, 사람이 읽을 수 있는 실패 설명입니다. 기계적으로 파싱되지 않으므로 대신 `error_type`을 기준으로 분기하세요. |
| `error_type` | [`RouterErrorType`](#routererrortype) | 예 | - | Router 실패에 대한 포괄적이고 기계 판독 가능한 분류로, 호출자가 본문을 파싱하지 않고 분기할 수 있도록 `X-Comfy-Error-Type` 응답 헤더에도 함께 반영됩니다. 이 집합은 열다섯 개 값으로 고정되어 있습니다: 요청 수준의 여섯 가지 분류 `invalid_input`, `content_policy_violation`, `provider_error`, `provider_timeout`, `insufficient_credits`, `model_not_found`와, 전송 수준의 `unauthorized`, `forbidden`, `concurrency_limit_exceeded`, `client_disconnected`, `internal_error`, `deadline_exceeded`, `not_enabled`, `service_unavailable`, `rate_limited`입니다. |
### RouterErrorType
기계가 읽을 수 있는 Router 오류 카테고리이며, `X-Comfy-Error-Type` 헤더로도 전송됩니다.
유형: `string`
### RouterModelBilling
모델을 호출하기 전에 확인해야 하는 과금 동작입니다. 가격이나 사용량은 포함하지 않습니다.
| 필드 | 타입 | 필수 | 제약 | 설명 |
| ----------------------------- | ------------------------------------------------------------------- | --- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `charges_on_policy_rejection` | [`RouterChargesOnPolicyRejection`](#routerchargesonpolicyrejection) | yes | - | 이 모델이 콘텐츠 정책을 이유로 거부한 호출도 호출자에게 과금되는지 여부입니다. 공급자마다 다르고, 그 차이는 호출 시점에 드러나지 않으며, 같은 호출에 대해 오류와 과금을 함께 보게 된 사용자는 미리 알 방법이 없었습니다. 따라서 공급자별 속설에 맡기는 대신 호출 이전에 모델별로 명시합니다. |
### RouterModelDetail
하나의 Comfy Router 모델에 대한 모델별 상세 정보입니다. 카탈로그 목록이 해당 모델에 대해 보고하는 모든 항목과, 단일 모델 경로만이 가지는 모델별 필드를 포함합니다.
[`RouterModelListEntry`](#routermodellistentry), [`RouterModelDetailFields`](#routermodeldetailfields)를 구성합니다.
타입: `object`
### RouterModelDetailFields
모델 세부 정보 엔드포인트에서 반환되는 선택적 필드입니다.
| 필드 | 타입 | 필수 | 제약 조건 | 설명 |
| ------------------ | ------ | --- | ------------------------------------------------------------------------------------- | ----------------------------------------- |
| `input_schema_url` | string | 아니요 | HTTPS URL, 예: `https://api.comfy.org/v2/models/bfl/flux-2-pro/openapi.json`, 최대 2048자 | 입력 및 출력 스키마를 포함한 이 모델의 OpenAPI 문서 URL입니다. |
### RouterModelId
`POST /v2/models/{provider}/{model}`에서 사용되는 모델 ID입니다.
타입: `string`. 모델 ID, 예: `anthropic/claude-opus-4-6`, 최대 193자
### RouterModelInput
모델 입력 객체입니다. 필드와 검증 항목은 선택된 모델의 OpenAPI 문서를 참조하세요.
타입: `object`
### RouterModelInputSchemaDocument
하나의 모델 입력과 출력을 위한 독립형 OpenAPI 문서입니다.
유형: `object`
### RouterModelListEntry
모델의 ID와 과금 정보입니다.
| 필드 | 타입 | 필수 | 제약 조건 | 설명 |
| ---------- | ------------------------------------------------- | -- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | [`RouterModelId`](#routermodelid) | 예 | 모델 ID, 예: `anthropic/claude-opus-4-6`, 최대 193자 | 정규 Comfy Router 모델 ID인 `{provider}/{model}`입니다. `POST /v2/models/{provider}/{model}`에서 모델을 지정하는 값과 정확히 동일하므로, 호출자는 다른 곳에서 다시 도출할 필요 없이 이 값을 해당 경로에 그대로 끼워 넣을 수 있습니다. `pattern`은 `RouterProviderSegment`와 `RouterModelSegment`를 단일 `/`로 결합한 것이며, `maxLength`는 두 길이의 합에 해당 구분자를 더한 값입니다. |
| `provider` | [`RouterProviderSegment`](#routerprovidersegment) | 예 | 영숫자 슬러그, 예: `anthropic`, 최대 64자 | 정규 `{provider}/{model}` 모델 ID의 소문자 `provider` 세그먼트로, 모델을 제공하는 파트너를 나타냅니다. 호출 라우트의 `provider` 경로 매개변수와 카탈로그 항목의 `provider` 필드는 모두 이 하나의 스키마를 참조하며, 이 덕분에 목록에 나열된 ID와 허용되는 ID가 서로 어긋나지 않습니다. |
| `model` | [`RouterModelSegment`](#routermodelsegment) | 예 | 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자 | 정규 `{provider}/{model}` 모델 ID의 소문자 `model` 세그먼트로, 해당 공급자 내에서 실행할 모델을 나타냅니다. 호출 라우트의 `model` 경로 매개변수와 카탈로그 항목의 `model` 필드가 이를 공유하며, 이는 `RouterProviderSegment`와 마찬가지로 ID가 어긋나지 않게 하기 위한 것입니다. |
| `billing` | [`RouterModelBilling`](#routermodelbilling) | 예 | - | 호출자가 호출하기 전에 알아야 하는 모델별 과금 사실 정보이며, 가격이 아닙니다. 사용량과 비용 수치는 여기에 절대 나타나지 않습니다. |
### RouterModelListResponse
라우터 모델 카탈로그의 한 페이지입니다.
| 필드 | 타입 | 필수 | 제약 | 설명 |
| ------------- | --------------------------------------------------- | --- | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `data` | [`RouterModelListEntry`](#routermodellistentry)의 배열 | 예 | - | 이 페이지에 있는 모델들로, 최대 `limit`개입니다. |
| `has_more` | 논리값 | 예 | - | 이 페이지 이후에 다른 페이지가 존재하는지 여부입니다. 이 값이 참인 동안 계속 순회하세요. `data`가 짧거나 비어 있다고 해서 카탈로그의 끝이라고 추론하지 마세요. |
| `next_cursor` | [`RouterPageCursor`](#routerpagecursor) | 아니오 | `next_cursor`로 반환되는 불투명 커서, 1-512자 | 라우터 목록을 가리키는 불투명(OPAQUE) 커서입니다. 이 커서는 서버에서 생성되며 오직 그대로 주고받기만 합니다. 오프셋도, 모델 ID도 아니고, 정렬되지도 않으며, 카탈로그가 다시 빌드되면 안정적이지도 않습니다. 따라서 커서를 파싱하거나, 값을 증가시키거나, 원래 순회했던 범위를 넘어 저장하는 것은 모두 계약 범위 밖입니다. 오프셋 대신 커서를 사용하는 이유는 카탈로그가 계속 변하는 목록이기 때문입니다. 오프셋 순회는 순회 도중 항목이 추가되거나 제거되면 조용히 항목을 건너뛰거나 반복하며, 호출자는 그런 일이 일어났는지 알 수 없습니다. |
| `limit` | 정수 | 예 | 1-100 | 실제로 제공된 페이지 크기입니다. 요청한 `limit`이 최댓값을 초과하면 거부되는 대신 최댓값으로 제한(CLAMP)되므로, 요청한 값보다 작을 수 있습니다. 보낸 값이 아니라 이 숫자를 기준으로 페이지네이션하세요. 그렇지 않으면 실제로 받지 못한 행이 있다고 착각하게 됩니다. |
### RouterModelOutput
모델 결과 객체입니다. 정확한 형태는 선택된 모델의 출력 스키마를 참고하세요.
유형: `object`
### RouterModelSegment
`{provider}/{model}` 모델 ID에서 모델에 해당하는 부분입니다.
타입: `string`: 영숫자 슬러그, 예: `claude-opus-4-6`, 최대 128자
### RouterPageCursor
불투명한 카탈로그 커서입니다. `cursor`로 변경 없이 그대로 다시 전달하세요.
Type: `string` -- `next_cursor`로 반환되는 불투명 커서, 1–512자
### RouterProviderSegment
`{provider}/{model}` 모델 ID의 공급자 부분입니다.
유형: `string`. 영숫자 슬러그, 예: `anthropic`, 최대 64자
### RouterQueueCancelResponse
이 라우트가 처리한 요청을 설명하는 두 상태, 즉 `202`와 `400`에 대한 취소 요청의 응답입니다. 성공 envelope과 오류 envelope을 따로 두지 않고 두 상태 모두에 하나의 body 형태를 사용하는데, 두 경우 모두 동일한 진술, 즉 취소가 무엇을 찾았는지를 나타내며, 상태 코드마다 다른 타입을 파싱해야 하는 클라이언트가 분리에서 얻는 이점은 없기 때문입니다.
| Field | Type | Required | Constraints | Description |
| ------------ | ----------------------------------------------------- | -------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| `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자 | 대기 중인 Router 요청 하나의 식별자로, 호출자가 폴링하고 취소하며 결과를 수집할 때 사용하는 핸들입니다. |
| `status` | [`RouterQueueCancelStatus`](#routerqueuecancelstatus) | 예 | - | 이 라우트가 실제로 처리한 요청을 설명하는 두 결과에 대해 취소 요청이 무엇을 찾았는지 나타냅니다. 두 결과 모두 HTTP 상태로 반영되므로 클라이언트는 어느 쪽으로든 분기할 수 있습니다. |
### RouterQueueCancelStatus
취소 요청이 찾아낸 결과로, 이 라우트가 실제로 처리한 요청을 설명하는 두 가지 결과에 해당합니다. 두 결과 모두 HTTP 상태 코드에 반영되므로 클라이언트는 어느 쪽으로든 분기할 수 있습니다.
유형: `string`
### RouterQueuePosition
응답이 구성된 시점에 실행 대기열에서 이 요청보다 앞에 있는 요청이 몇 개인지를 나타냅니다. 0이면 이 요청이 맨 앞에 있습니다.
타입: `integer` -- 최소 0
### RouterQueueRequestId
대기 중인 Router 요청 하나의 식별자입니다. 호출자가 폴링하고, 취소하고, 결과를 수집하는 데 사용하는 핸들입니다.
Type: `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 블록이 아닌 나머지 절반으로, 대기 중인 요청 하나의 식별자와 현재 상태, 그리고 그 상태가 터미널이고 실행이 성공하지 못했을 때 그 이유를 나타내는 포괄적인 분류를 담습니다.
| 필드 | 타입 | 필수 | 제약 조건 | 설명 |
| ---------------- | ----------------------------------------------- | --- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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자 | 대기 중인 Router 요청 하나의 식별자로, 호출자가 폴링하고 취소하며 결과를 수집할 때 사용하는 핸들입니다. |
| `status` | [`RouterQueueStatus`](#routerqueuestatus) | 예 | - | 대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며, `RouterErrorType`과 달리 이 스키마는 닫힌 `enum`입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. `RouterErrorType`은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식되지 않은 분류를 강하게 거부하는 생성된 클라이언트는 이미 무언가 잘못된 상황에서 가장 크게 실패하게 됩니다. 반면 이 값은 수명 주기이며, 나중에 네 번째 상태가 추가된 수명 주기는 enum으로 선언되었는지 여부와 관계없이 그에 맞춰 작성된 모든 폴링 루프에 대한 호환성을 깨는 변경입니다. 그래서 enum으로 선언하고, 클라이언트가 볼 수 있는 곳에 제약을 명시합니다. |
| `queue_position` | [`RouterQueuePosition`](#routerqueueposition) | 아니요 | 0 이상 | 응답이 구성된 즉시 이 요청보다 실행 대기열에서 앞에 있는 요청의 수입니다. 0이면 이 요청이 맨 앞에 있습니다. |
| `error_type` | [`RouterErrorType`](#routererrortype) | 아니요 | - | 성공하지 못한 `COMPLETED` 요청에만 존재하며, 결과 조회가 해당 실패를 반환할 때 `X-Comfy-Error-Type`에 담는 것과 동일한 포괄적인 분류를 담습니다. 이것이 성공한 터미널 요청과 실패했거나 취소된 요청을 구분하는 기준입니다. 어느 쪽도 별도의 터미널 상태가 없습니다. 또한 성공 시에는 null이 아니라 아예 존재하지 않으므로, 존재 여부로 분기하세요. |
### RouterQueueStatusResponse
대기 중인 요청 하나의 현재 상태이며, 제출 시 반환된 것과 동일한 세 개의 URL로 구성됩니다.
다음 스키마를 구성 요소로 포함합니다: [`RouterQueueUrls`](#routerqueueurls), [`RouterQueueStatusFields`](#routerqueuestatusfields).
유형: `object`
### RouterQueueSubmitFields
`RouterQueueSubmitResponse`에서 URL 블록이 아닌 나머지 절반: 새 요청의 식별자와 요청이 접수된 즉시의 상태입니다.
| 필드 | 타입 | 필수 | 제약 | 설명 |
| ---------------- | ----------------------------------------------- | --- | --------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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자 | 대기 중인 Router 요청 하나의 식별자: 호출자가 폴링하고, 취소하고, 결과를 수집하는 데 사용하는 핸들입니다. |
| `status` | [`RouterQueueStatus`](#routerqueuestatus) | 예 | - | 대기 중인 Router 요청의 상태입니다. 정확히 세 개의 값을 가지며, `RouterErrorType`과 달리 이 스키마는 닫힌 `enum`입니다. 두 스키마가 의도적으로 서로 반대 방향으로 닫혀 있기 때문입니다. `RouterErrorType`은 실패를 분류하며 그 집합은 늘어날 것으로 예상되므로, 인식되지 않은 버킷을 강하게 거부하는 생성된 클라이언트는 이미 문제가 발생한 바로 그 순간에 가장 크게 실패하게 됩니다. 이 스키마는 라이프사이클이며, 나중에 네 번째 상태가 추가된 라이프사이클은 enum으로 선언되었든 아니든 그것에 맞춰 작성된 모든 폴링 루프에 대한 호환성을 깨는 변경입니다. 그래서 enum으로 선언하고, 제약을 클라이언트가 볼 수 있는 곳에 명시합니다. |
| `queue_position` | [`RouterQueuePosition`](#routerqueueposition) | 아니요 | 0 이상 | 응답이 구성된 즉시 이 요청보다 실행 대기열에서 앞에 있는 요청이 몇 개인지입니다. 0이면 이 요청이 맨 앞에 있습니다. |
### RouterQueueSubmitResponse
실행이 실행 대기열에 등록될 때 반환되는 핸들로, 요청의 식별자와 상태에 나머지 수명 주기를 다루는 세 개의 URL을 결합한 것입니다.
다음을 구성합니다: [`RouterQueueUrls`](#routerqueueurls), [`RouterQueueSubmitFields`](#routerqueuesubmitfields).
타입: `object`
### RouterQueueUrls
대기 중인 요청의 남은 수명 주기를 처리하는 세 개의 URL입니다. 활성 핸들을 포함하는 모든 응답에서 반환되므로, 클라이언트가 직접 실행 대기열 URL을 구성할 필요가 없습니다.
| 필드 | 유형 | 필수 | 제약 | 설명 |
| -------------- | --- | -- | --- | ------------------------- |
| `status_url` | 문자열 | 예 | URI | 이 요청의 상태를 조회하는 절대 URL입니다. |
| `response_url` | 문자열 | 예 | URI | 이 요청의 결과를 수집하는 절대 URL입니다. |
| `cancel_url` | 문자열 | 예 | URI | 취소를 요청하는 절대 URL입니다. |
### RouterValidationErrorContext
실패한 검증 규칙에 대해 공급자가 제공하는 세부 정보입니다.
유형: `object`
### RouterValidationErrorDetail
단일 필드 수준 검증 실패입니다.
| 필드 | 타입 | 필수 | 제약 | 설명 |
| ------- | --------------------------------------------------------------- | --- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `loc` | any의 배열 | 예 | - | 문제가 된 필드의 경로이며 가장 바깥쪽 세그먼트가 먼저 옵니다. 예를 들어 `["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}`입니다. 키 집합은 공급자와 오류 타입에 따라 달라지므로, 이는 의도적으로 열린 객체입니다. 고정된 필드 목록으로 좁히거나 `msg` 문자열에 합쳐 버리면, 포팅된 통합이 컴파일은 되지만 경계를 읽던 분기를 조용히 잃게 됩니다. 오류 타입에 경계가 없으면 이 필드는 존재하지 않습니다. |
| `input` | [`RouterValidationErrorInput`](#routervalidationerrorinput) | 아니요 | - | 문제가 된 입력 값으로, 호출자가 `loc`에서 다시 도출하지 않고도 무엇이 거부되었는지 확인할 수 있도록 그대로 되돌려 전달됩니다. 문자열, 숫자, 논리값, 배열, 객체 또는 null 등 모든 JSON 타입이 될 수 있으므로, 이 스키마는 객체로 좁히지 않고 의도적으로 타입 없이 둡니다. 공급자가 입력을 되돌려 전달하지 않으면 존재하지 않습니다. |
### RouterValidationErrorInput
공급자가 해당 값을 포함할 때 거부된 입력 값입니다.
### RouterValidationErrorResponse
`422` 검증 오류 본문입니다. 해당 카테고리는 `X-Comfy-Error-Type`을 확인하세요.
| 필드 | 타입 | 필수 | 제약 | 설명 |
| -------- | ---------------------------------------------------------------- | -- | -- | -------------------------------------------------- |
| `detail` | [`RouterValidationErrorDetail`](#routervalidationerrordetail) 배열 | 예 | - | 요청에서 발견된 모든 검증 실패 항목으로, 문제가 있는 필드마다 하나의 항목이 대응됩니다. |