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가 참인 동안 next_cursor를 사용하세요.
파라미터
응답
GET /v2/models/{provider}/{model}
정식 모델 ID로 파트너 모델 하나의 카탈로그 항목을 조회합니다.
전체 카탈로그를 나열하지 않고 하나의 모델에 대한 세부 정보를 조회합니다.
파라미터
응답
POST /v2/models/{provider}/{model}
정식 모델 ID로 파트너 모델을 동기식으로 실행합니다.
모델을 실행하고 완료된 결과를 동일한 응답으로 받습니다.
파라미터
요청 본문
application/json — RouterModelInput (필수)
파트너 모델의 네이티브 JSON 입력으로, 변경 없이 공급자에게 전달됩니다.
응답
GET /v2/models/{provider}/{model}/openapi.json
하나의 파트너 모델의 입력 및 출력 스키마를 OpenAPI 문서로 읽습니다.
하나의 모델의 입력 및 출력 스키마를 독립 실행형 OpenAPI 문서로 읽습니다.
파라미터
응답
POST /v2/models/{provider}/{model}/requests
파트너 모델 실행을 실행 대기열에 제출하고 즉시 반환합니다.
Comfy Router의 QUEUED 전달 모드입니다. 요청 본문은 이 모델에 대해 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을 확인하세요.