2026-09-26개발자

Sume API 카탈로그: 사용 가능한 모델·엔드포인트·가격 조회

GET /v1/catalog는 Sume API 기능을 모델 ID, 호출 URL, 가용성, 런타임 준비 상태, 가격과 함께 나열합니다. API 키가 필요 없습니다.

읽는 시간 5분Sume

Sume API에서 사용할 수 있는 모델과 기능을 나열하려면 GET /v1/catalog를 호출하세요. API 키가 필요 없으며, 기능마다 항목을 하나씩 반환하고 각 항목에는 Sume 모델 ID, 엔드포인트 경로, 가용성, 런타임 준비 상태, 가격 메타데이터가 담깁니다. 그래서 문서는 프로그램 방식 탐색의 출발점으로 이 엔드포인트를 권합니다.

아래 필드는 Sume 문서 핵심 개념과 API 레퍼런스, 그리고 라이브 Sume API 레퍼런스의 카탈로그 스키마에서 가져왔으며, 2026-09-26에 확인했습니다.

카탈로그는 어떻게 호출하나요?

일반 GET 요청을 보내세요. 몇 안 되는 공개 경로를 제외한 모든 /v1 엔드포인트에는 API 키가 필요한데, GET /v1/catalog는 GET /v1/health, GET /v1/openapi.json과 함께 그 공개 경로 목록에 있습니다. 아래에서 설명하듯, 자신의 워크스페이스가 내는 가격을 보려면 키를 보내세요. TypeScript SDK에서 생성된 함수는 listPublicApiCapabilities입니다.

curl -s https://api.sume.com/v1/catalog \
  | jq '.data[] | {id, api_type, invoke_url, availability, beta}'

카탈로그 항목에는 무엇이 들어 있나요?

응답에는 apiVersion, status, 그리고 기능마다 항목이 하나씩 담긴 data 배열이 있습니다. 연동의 기반으로 삼을 필드는 다음과 같습니다.

Sume API 레퍼런스와 API 레퍼런스 문서 기준 카탈로그 항목 필드, 2026-09-26 확인.
필드	의미
`api_type`	`model_api`, `resource_api`, `job_api`, `asset_api` 중 하나
`model_id`, `model_ids`	원본 프로바이더 엔드포인트 ID를 숨기는 Sume 소유의 공개 모델 ID. 모델이 아닌 유틸리티에서는 `model_id`가 `null`
`invoke_url`	기본 공개 호출 URL. 읽기 전용 기능이면 `null`
`endpoints`, `resource_endpoints`	기능의 엔드포인트 경로, 그리고 안정적인 별칭이나 더 풍부한 리소스 API로 남아 있는 리소스 엔드포인트
`availability`	현재 API 런타임 기준 `available`, `degraded`, `unavailable`, `coming_soon` 중 하나
`unavailable_reason`, `degraded_reason`	기능을 쓸 수 없거나, 알려진 제약이 있는 채로 쓸 수 있을 때 공개해도 안전한 사유
`beta`	공개 베타 기능이면 `true`
`runtime`	`generation_configured`, `worker_configured`, `media_mirror_configured` 플래그
`billing`	`requires_balance`, `top_up_available` 플래그

호출하기 전에 모델을 쓸 수 있는지 어떻게 확인하나요?

status가 아니라 availability를 읽으세요. 스키마는 status를 하위 호환용으로 사람이 읽는 준비 상태 문자열로 유지하고, 기계적인 판단에는 availability, runtime, billing을 쓰라고 안내합니다. beta: true는 전체 프로바이더 워크플로가 정식 제공되기 전에 계약이 먼저 제공되는 기능을 표시합니다.

Generation admission 문서는 404 model_not_found를 받으면 /v1/catalog를 쓰거나 ID를 확인하라고 안내합니다.
503 provider_not_configured를 재시도하기 전에는 공격적으로 재시도하지 말고 카탈로그와 런타임 상태를 확인하세요.
내부 음성 기능, 원본 프로바이더 모델 ID, 프로바이더 task URL은 /v1/catalog와 OpenAPI 스키마에 나오지 않는 한 공개 API가 아닙니다.

카탈로그는 가격을 어떻게 보여 주나요?

유료 기능에는 billing_unit: usd_cent, billable_amount: sume_price, reservation_policy가 담긴 USD 기준 pricing 블록이 있습니다. 각 model_pricing[] 항목에는 estimated_usd_cents, minimum_usd_cents, maximum_usd_cents, pricing_basis가 더해지고, title, price, unit 문자열이 담길 수도 있습니다. 이 값들은 반올림한 추정치입니다. 제출 시점의 예약은 정확한 USD 마이크로 단위로 저장되며, 노출될 때는 센트 단위로 올림됩니다.

applied_*_usd_cents 필드는 인증된 워크스페이스가 자기 가격표에 따라 실제로 내는 추정액이며, 모델 항목(applied_model_estimated_usd_cents)과 에이전트 수수료 항목(applied_agent_fee_estimated_usd_cents)으로 나뉩니다. price_book은 그 근거가 되는 조건을 discount_bps와 agent_fee_bps로 밝힙니다. 사용량은 기본적으로 공개 요율에 5.5% 에이전트 수수료를 더해 청구됩니다.

API 요금의 요율표도 이곳을 가리킵니다. 관리형 모델과 라우터의 전체 요율은 GET /v1/catalog에 있습니다.

카탈로그는 GET /v1/videos/models와 같은가요?

아닙니다. GET /v1/videos/models는 영상 생성 모델만 나열하며, 모델마다 지원하는 해상도, 길이, 가격 SKU가 함께 나옵니다. 이 엔드포인트는 OpenRouter 호환 영상 API에서 다룹니다. 카탈로그는 영상 외의 기능도 다룹니다. 모델 ID는 sume/avatar-1.0/generate와 sume/music-router부터 sume/timeline-1.0, sume/video-trim-1.0 같은 미디어 도구까지 이어집니다.

카탈로그로 알 수 없는 것은 무엇인가요?

카탈로그는 계약 전체가 아니라 기능의 지도입니다.

요청 필드: 정확한 요청·응답 스키마는 https://api.sume.com/reference/json의 라이브 OpenAPI에 있습니다.
Format: GET /v1/formats는 요청한 키로 볼 수 있는 Format을 나열합니다. 직접 만든 Format과 first-party 카탈로그입니다.
청구 금액: 카탈로그의 센트 값은 추정치이며, 청구 기록은 GET /v1/usage와 GET /v1/balance입니다.

출처

작성자 Sume