POST /v2/models/{provider}/{model}를 사용합니다. 이 페이지에서는 모델 간에 공유되는 헤더를 다루며, API reference에는 생성된 계약이 나열되어 있습니다.
Comfy SDK(comfy-sdk는 Python용, @comfyorg/sdk는 TypeScript용)는 인증을 처리하고 idempotency key를 생성합니다. 아래에 설명된 대로 선택된 응답 메타데이터를 노출합니다. Raw HTTP 클라이언트는 헤더를 직접 전송하고 읽어야 합니다.
요청 헤더
string
Comfy 워크스페이스에서 생성한
comfyui-... 형식의 Comfy API 키입니다. 이 키는 워크스페이스의 모델 접근 권한과 크레딧 잔액을 사용합니다. Authorization: Bearer comfyui-... 형식으로 보낼 수도 있으며, 두 헤더가 모두 있으면 X-API-Key가 우선합니다.string
Bearer <token>. comfyui- 값은 API 키입니다. 그 외의 값은 Comfy Cloud JWT로 처리됩니다.string
하나의 논리적 생성을 식별합니다. 호출 전에 UUID를 생성해 저장한 뒤, 변경되지 않은 요청을 재시도할 때 재사용하세요. 이 키는 최대 24시간 동안 결과를 재생하거나 수락된 작업을 수집할 수 있습니다. SDK는 키를 자동으로 생성하며 직접 지정할 수도 있습니다(Python에서는
idempotency_key=, TypeScript에서는 idempotencyKey). 충돌, 만료, 재생 불가능한 결과에 대해서는 재시도 결과를 참조하세요.string
application/json. 모델의 네이티브 JSON 입력을 전송합니다. 필드와 검증 요구 사항은 모델마다 다릅니다. Router API 사용하기를 참조하세요.string
GET /v2/models/{provider}/{model}/openapi.json에서만 사용합니다. 이전 200 응답에서 받은 ETag를 전송하세요. 여전히 일치하면 동일한 ETag와 함께 본문 없는 304가 반환됩니다. 모델의 스키마를 프로세스가 실행되는 동안 캐시하고, 매 호출 전에 다시 읽는 대신 이 방식으로 재검증하세요.응답 헤더
string
필수
이 HTTP 요청을 식별합니다. 지원팀에 문의할 때 이 값을 포함하세요. TypeScript에서는
requestId로, Python에서는 오류 시 request_id로 노출됩니다.string
기계 판독 가능한 오류 카테고리입니다.
422에서는 검증 본문에 detail[]이 있고 error_type이 없으므로 이 헤더를 사용하세요. HTTP 상태와 결합하여 어떻게 처리할지 판단하세요. 알 수 없는 값은 제어 흐름에서는 internal_error로 취급하고, 진단을 위해 그대로 보존하세요.boolean
Router가 모델을 다시 실행하지 않고 저장된 결과를 제공할 때 존재하며
true입니다. 새 실행에서는 없습니다. 대기열 제출 라우트에서는 재생된 201이 두 번째 실행을 대기열에 넣지 않고 원래 요청 핸들을 반환합니다.integer
재시도하기 전에 기다릴 초입니다.
409 / concurrency_limit_exceeded 또는 504 / deadline_exceeded에서는 대기 후 동일한 요청과 키로 재시도하세요. 429 / rate_limited에서는 속도 제한이 초기화되는 시점을 알려줍니다. 대기열에 넣은 요청의 상태 조회와 202 결과 조회에서는 다시 폴링할 가치가 있는 시점에 대한 Router의 힌트입니다.integer
아직 실행 중인 호출에 커밋된 파트너 지출의 상한(USD 센트)입니다. 지출 게이트를 적용하는 경우 승인된 응답과
429 거부 응답에 이 값을 반환할 수 있습니다. 게이트가 적용되지 않거나 다른 제어가 요청을 거부한 경우에는 없습니다.integer
현재 진행 중인 호출에 커밋된 USD 센트입니다. 승인된 응답에는 해당 호출 자체가 포함되며
429에는 거부된 호출이 제외됩니다. X-Committed-Spend-Limit와 함께 전송됩니다.integer
커밋된 지출 상한 아래에 남은 USD 센트입니다. 요청한 호출 비용이 남은 금액보다 클 때 거부 응답에서 양수일 수 있습니다.
string
GET /v2/models/{provider}/{model}/openapi.json에서 사용합니다. 이를 저장하고 If-None-Match로 다시 보내 캐시된 스키마를 재검증하세요.string
스키마 라우트에서는
private, must-revalidate입니다. 응답을 프라이빗 캐시에 보관하고 ETag로 오래된 사본을 재검증하세요.두 가지 의미를 지닌 상태 코드
세 가지 상태는 두 버킷에 걸쳐 공유되며, 이를 구분해 주는 것이 바로 헤더입니다:다음
- 퀵스타트: 요청을 보내고 결과를 확인합니다.
- Comfy Router API 사용하기: 모델 검색, 스키마, 오류, 재시도, 과금.
- API 레퍼런스: 이 헤더들이 정의된 생성된 계약.
- 제한 사항: 현재 Router가 하지 않는 것과 대신 사용할 것.