Comfy Router API 레퍼런스

Comfy Router의 정식 라우트로, 모델 ID로 주소가 지정됩니다. 기본 URL: https://api.comfy.org 아래의 모든 엔드포인트에는 인증이 필요합니다. X-API-Key: <api-key> 또는 Authorization: Bearer <jwt>를 전송하십시오. Comfy API 키는 Bearer 토큰으로도 전송할 수 있습니다. 두 자격 증명 헤더를 모두 제공하면 X-API-Key가 우선합니다. 키와 JWT의 구분은 인증 헤더를, 액세스 요구 사항은 퀵스타트를 참고하십시오.

​

엔드포인트

​

GET /v2/models

Comfy Router가 실행할 수 있는 모델을 나열합니다. 사용 가능한 모델 ID와 과금 정보를 나열합니다. has_more가 true인 동안 next_cursor를 사용하세요. 파라미터 응답

​

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

정식 모델 ID로 파트너 모델 하나의 카탈로그 항목을 조회합니다. 전체 카탈로그를 나열하지 않고 모델 하나의 세부 정보를 읽습니다. 파라미터 응답

​

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

정규 모델 ID로 파트너 모델을 동기적으로 실행합니다. 모델을 실행하고 완료된 결과를 같은 응답에서 받습니다. 파라미터 요청 본문 application/json — RouterModelInput (필수) 파트너 모델의 고유 JSON 입력입니다. model_provider가 없거나 strict_mode=true인 경우 공급자에게 변경 없이 전달됩니다. strict_mode=true에서는 본문이 이미 이 모델의 고유 스키마가 아니라 대체 공급자 자체의 실제 스키마여야 합니다(strict_mode 참조). model_provider로 대체 공급자를 선택하고 strict_mode=false(기본값)인 경우, 본문은 전송되기 전에 해당 공급자의 실제 스키마로 변환됩니다. 정확히 표현할 수 없는 고유 필드는 조용히 처리되지 않고 삭제되며 응답의 X-Comfy-Router-Dropped-Params 헤더를 통해 공개됩니다. 응답

​

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

파트너 모델 하나의 입력 및 출력 스키마를 OpenAPI 문서로 읽어옵니다. 모델 하나의 입력 및 출력 스키마를 독립형 OpenAPI 문서로 읽어옵니다. 파라미터 응답

​

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

파트너 모델 실행을 대기열에 제출하고 즉시 반환합니다. Comfy Router의 대기열 전달 모드입니다. 요청 본문은 이 모델에 대해 POST /v2/models/{provider}/{model}이 수용하는 것과 동일한 파트너 네이티브 JSON 입력입니다. 하나의 본문 형태, 모델별 스키마 하나, 두 가지 전달 모드이지만, 이 경로는 결과를 위해 연결을 유지하지 않습니다. 실행을 승인하고 핸들과 함께 201로 응답하며, 호출자는 아래 세 가지 읽기 작업을 통해 나중에 결과를 수집합니다. 파라미터 요청 본문 application/json — RouterModelInput (필수) 파트너 모델의 네이티브 JSON 입력으로, 이 모델에 대해 동기 경로가 수용하는 본문과 동일합니다. 실행이 승인되기 전에 모델 자체의 입력 스키마에 대해 검증되므로, 모델이 거부할 본문은 몇 분 후에 실패하는 대기 중 요청이 아니라 여기서 422가 됩니다. 응답

​

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

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

​

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

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

​

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

제출된 요청 하나의 실행 대기열 상태를 조회합니다. 폴링 엔드포인트입니다. 요청의 현재 상태만 응답하며 결과는 절대 반환하지 않으므로, 클라이언트는 매 폴링마다 출력을 전송받지 않고도 오래 걸리는 생성을 지켜볼 수 있습니다. 결과는 이 응답이 COMPLETED를 나타낼 때 아래의 조회를 통해 한 번만 수집합니다. 파라미터 응답 여기의 설명은 간략합니다. 모델 선택, 검증, 재시도, 과금에 대해서는 Comfy Router API 사용하기를, 헤더 동작에 대해서는 헤더를 참고하세요.

​

오류 버킷

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

​

요청 수준 버킷

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

​

전송 수준 버킷

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

​

응답 헤더

​

결과 에셋

모델은 에셋 URL, 인라인 바이트, 또는 둘 다를 반환할 수 있습니다. 아래 공급자는 선택된 에셋을 Comfy 스토리지로 복사하고 해당 URL을 대체합니다. 이 동작은 모델에 따라 다르며, 이를 선택하는 요청 헤더는 없습니다. 이 수명은 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

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

​

RouterErrorType

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

​

RouterModelBilling

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

​

RouterModelDetail

하나의 Comfy Router 모델에 대한 모델별 상세 정보입니다. 카탈로그 목록이 해당 모델에 대해 보고하는 모든 항목과, 단일 모델 경로만이 가지는 모델별 필드를 포함합니다. RouterModelListEntry, RouterModelDetailFields를 구성합니다. 타입: object

​

RouterModelDetailFields

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

​

RouterModelId

POST /v2/models/{provider}/{model}에서 사용되는 모델 ID입니다. 타입: string. 모델 ID, 예: anthropic/claude-opus-4-6, 최대 193자

​

RouterModelInput

모델 입력 객체입니다. 필드와 검증 항목은 선택된 모델의 OpenAPI 문서를 참조하세요. 타입: object

​

RouterModelInputSchemaDocument

하나의 모델에 대한 입력과 출력을 담은 독립형 OpenAPI 문서입니다. 유형: object

​

RouterModelListEntry

모델의 ID와 과금 정보입니다. 필드

​

RouterModelListResponse

라우터 모델 카탈로그의 한 페이지입니다. 필드

​

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 형태를 사용하는데, 두 경우 모두 동일한 진술, 즉 취소가 무엇을 찾았는지를 나타내며, 상태 코드마다 다른 타입을 파싱해야 하는 클라이언트가 분리에서 얻는 이점은 없기 때문입니다. 필드

​

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 블록이 아닌 나머지 절반으로, 대기 중인 요청 하나의 식별자, 현재 상태, 그리고 그 상태가 터미널이고 실행이 성공하지 못했을 때 그 이유를 나타내는 포괄적인 분류를 담습니다. 필드

​

RouterQueueStatusResponse

대기 중인 요청 하나의 현재 상태이며, 제출 시 반환된 것과 동일한 세 개의 URL로 구성됩니다. 다음 스키마를 구성 요소로 포함합니다: RouterQueueUrls, RouterQueueStatusFields. 유형: object

​

RouterQueueSubmitFields

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

​

RouterQueueSubmitResponse

실행이 실행 대기열에 등록될 때 반환되는 핸들로, 요청의 식별자와 상태에 나머지 수명 주기를 다루는 세 개의 URL을 결합한 것입니다. 다음을 구성합니다: RouterQueueUrls, RouterQueueSubmitFields. 타입: object

​

RouterQueueUrls

대기 중인 요청의 남은 수명 주기를 처리하는 세 개의 URL로, 활성 핸들을 포함하는 모든 응답에서 반환되므로 클라이언트가 실행 대기열 URL을 직접 구성할 필요가 없습니다. 필드

​

RouterValidationErrorContext

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

​

RouterValidationErrorDetail

단일 필드 수준 검증 실패입니다. 필드

​

RouterValidationErrorInput

공급자가 해당 값을 포함할 때 거부된 입력 값입니다.

​

RouterValidationErrorResponse

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