Sume API OpenAPI 스펙: 다운로드·탐색·클라이언트 생성

Sume API의 OpenAPI 스펙은 https://api.sume.com/reference/json에서 라이브로 제공되며, 같은 API를 api.sume.com/reference의 Swagger UI에서 살펴볼 수 있습니다. curl 한 번으로 내려받고, 공식 TypeScript SDK를 쓰든 클라이언트를 직접 생성하든 요청·응답 필드의 정확한 기준으로 삼으세요.

아래 URL과 규칙은 Sume 문서 API 레퍼런스와 Developer API 개요 (영문), 그리고 스키마 자체에서 가져왔으며, 2026-09-26에 확인했습니다.

Sume OpenAPI 스펙은 어디서 내려받나요?

라이브 스키마를 가져오세요. API 레퍼런스의 다운로드 명령은 한 줄이며, GET /v1/openapi.json도 API 키가 필요 없는 몇 안 되는 /v1 경로 중 하나입니다.

curl https://api.sume.com/reference/json \
  -o sume-openapi.json

OpenAPI 스펙과 문서 중 무엇이 기준인가요?

스펙입니다. API 레퍼런스 페이지는 스스로를 두 번째 스키마가 아니라 사람이 읽기 쉬운 라우트 맵이라고 설명하며, 그 Markdown 표는 뒤처질 수 있다고 경고합니다. 정확한 JSON 형태, enum, 필수 필드는 라이브 OpenAPI 문서에서 옵니다. 이 문서는 OpenAPI 3.0.3이며, 모든 클라이언트에 필요한 규칙 두 가지를 명시합니다.

• x-api-key나 Authorization: Bearer로 인증하되, 정확히 하나만 보내세요. 둘 다 실은 요청은 401 unauthorized로 거부됩니다. 스코프와 교체는 Sume API 키 동작 방식에서 다룹니다.
• 오류 code 값은 항상 정규식 ^[a-z0-9_]+$에 맞습니다. code로 분기하세요. message는 사람을 위해 쓴 문구라 바뀔 수 있습니다.

Sume는 어떤 클라이언트 라이브러리를 배포하나요?

공식 TypeScript 클라이언트인 @sume-com/sdk는 같은 스키마에서 생성됩니다. 오퍼레이션 하나당 함수가 하나이고 오퍼레이션 ID를 따라 이름이 붙으며, 그 위에 손으로 작성한 헬퍼가 얹혀 있습니다. 문서는 이 SDK를 두 번째 계약이 아니라 편의 계층이라고 부릅니다. 자세한 내용은 Sume TypeScript SDK 빠른 시작에서 다룹니다.

다른 언어에 대한 문서의 답은 일반 HTTP입니다. 어떤 HTTP 클라이언트로도 제출, 폴링, 결과 조회 루프를 돌릴 수 있습니다. 문서의 Kotlin 예시 스케치에는 Sume가 Kotlin 패키지를 배포하지 않는다는 설명이 덧붙어 있습니다.

스펙에서 클라이언트는 어떻게 생성하나요?

사용하는 언어의 OpenAPI 3.0 코드 생성기에 내려받은 파일을 지정하세요. 모든 오퍼레이션에는 createVideoGeneration이나 getApiJob 같은 operationId가 있으며, TypeScript SDK는 이 값을 함수 이름으로 씁니다. 그런 다음 생성기가 알 수 없는 부분을 처리하세요.

• 숨겨진 경로는 스펙에 없습니다. 에셋 업로드 계열, admission 프리뷰, 범용 /v1/models/{model_owner}/{model_name}/{model_version}/runs 템플릿처럼 구현은 되어 있지만 일부러 뺀 경로가 있습니다. 라이브 스키마에 나타나기 전까지는 이런 경로를 전제로 만들지 마세요. 미디어는 생성 요청에 공개 HTTPS URL을 쓰는 편이 좋다고 문서가 안내합니다.
• 선언되지 않은 상태 코드도 있습니다. 스케줄 실행 경로인 POST /v1/actions/{action_id}/runs는 200, 202, 400, 401, 403, 404, 409, 413, 429, 500을 선언하지만, 업스트림 계층에서 발생하는 503은 이 목록에 없으므로 생성된 클라이언트가 이를 모델링하지 못할 수 있습니다.
• 요약에 라벨이 붙은 오퍼레이션도 있습니다. Beta로 표시된 Avatar Face Swap 1.0 모델 실행이 그런 예입니다. 이런 오퍼레이션을 전제로 만들기 전에 GET /v1/catalog에서 availability와 beta를 확인하세요.

SDK 없이 쓰면 무엇을 직접 작성해야 하나요?

SDK의 헬퍼에는 대응하는 REST 엔드포인트가 없으므로, 생성된 클라이언트를 쓰면 이 부분은 직접 만들어야 합니다.

• 대기 루프: mode: "async"와 Idempotency-Key로 제출하고, next_poll_after_seconds를 따르며 GET /v1/jobs/{id}/status를 폴링하고, terminal이 true가 되면 멈춘 뒤, result_ready가 true가 되면 /result를 읽으세요. 마감 시간은 클라이언트 쪽에서 정하며, 문서는 영상에 20분이 적당하다고 설명합니다.
• 웹훅 검증: Sume는 <timestamp>.<raw_body>에 대해 HMAC-SHA256으로 서명하고 x-sume-webhook-signature에 sume-v1=<hex>를 담아 보냅니다. 파싱하기 전에 원본 본문을 검증하고, 재전송 허용 시간을 벗어난 타임스탬프는 거부하고, sume-v1= 항목 중 하나라도 일치하면 전달을 수락하세요. 시크릿 교체 중에는 헤더에 유효한 시크릿마다 서명이 하나씩 실리기 때문입니다. 전체 스킴은 Sume 영상 실행용 서명된 웹훅에 있습니다.