Sume TypeScript SDK 빠른 시작: 설치·클라이언트·오류·재시도

Sume TypeScript SDK는 api.sume.com의 공식 TypeScript 클라이언트인 @sume-com/sdk입니다. npm install @sume-com/sdk로 설치하고, createSumeClient({ apiKey })로 클라이언트 하나를 만든 뒤, 모든 호출에 그 클라이언트를 넘기세요. 공개 OpenAPI 스키마의 모든 오퍼레이션을 다루고, 실행과 Job을 기다리고 웹훅을 검증하는 헬퍼를 더하며, 일시적인 실패는 기본으로 재시도합니다.

아래 내용은 모두 Sume 문서의 TypeScript SDK와 실행 기다리기 (영문) 페이지에서 가져왔으며, 2026-09-26에 확인했습니다.

Sume TypeScript SDK는 어떻게 설치하나요?

npm install @sume-com/sdk를 실행하세요. 문서가 밝히는 배포 버전은 0.2.0이며, MIT 라이선스이고 런타임 의존성이 없습니다. fetch와 WebCrypto가 필요하며, 문서는 Node 18 이상, Bun, Deno, Cloudflare Workers를 명시합니다.

서버에서만 사용하세요. 제품에 AI 영상 생성을 임베드하는 방법에서 설명하듯, Sume API 키는 크레딧을 소모하며 브라우저에서 안전하게 쓸 수 있는 변형이 없습니다.

클라이언트는 어떻게 만드나요?

createSumeClient를 한 번 호출하고, 그 클라이언트를 모든 호출에 넘기세요. 오퍼레이션은 모듈 수준의 기본 클라이언트도 받지만, 그 기본 클라이언트에는 API 키가 없습니다. 생성된 코드가 컴파일되게 하려고 있는 것이지, 팩토리를 건너뛰라고 있는 것이 아닙니다.

import { createSumeClient, listFormats } from "@sume-com/sdk";

const client = createSumeClient({ apiKey: process.env.SUME_API_KEY! });

const { data, error } = await listFormats({ client });
if (error) throw new Error(JSON.stringify(error));

SDK는 어떤 인증 헤더를 보내나요?

클라이언트는 x-api-key만 보내고 Authorization은 설정하지 않습니다. API는 두 헤더 중 하나만 보내면 받아들이지만, 둘을 함께 보내면 401 unauthorized와 Send only one API key credential. 메시지로 거부합니다. 어느 헤더도 우선하지 않으므로, 게이트웨이 자격 증명이나 인터셉터가 Authorization을 추가하면 x-api-key가 맞았더라도 요청이 실패합니다. 직접 만든 fetch를 넘긴다면 이 헤더를 추가하지 않는지 확인하세요.

Format을 실행하려면 formats:read와 formats:write가 있는 키도 필요하며, 팀 Format에는 그 팀의 워크스페이스에서 만든 키가 필요합니다. 스코프와 403 코드는 Sume API 키 동작 방식에서 다룹니다.

생성된 오퍼레이션은 무엇인가요?

패키지가 내보내는 것 중 팩토리와 헬퍼를 뺀 나머지는 모두 API 레퍼런스와 같은 OpenAPI 스키마에서 생성됩니다. 오퍼레이션 하나당 함수가 하나이며, listFormats, createFormatRun, getFormatRunStatus, cancelFormatRun처럼 오퍼레이션 ID를 따라 이름이 붙습니다. 전체 목록은 에디터의 자동완성에서 확인하라고 문서가 안내합니다. 정확한 요청·응답 필드는 API 레퍼런스와 https://api.sume.com/reference/json의 라이브 OpenAPI에 있으며, 기준은 계속 이 둘입니다.

생성된 오퍼레이션은 API 오류가 나도 throw하지 않습니다. { data, error, response }로 resolve하므로 data를 읽기 전에 error를 확인하세요. 그 위에 손으로 작성한 헬퍼로는 다음이 있습니다.

• subscribeFormatRun: Format 실행을 만들고 종료 영수증을 기다립니다.
• waitForRun: 실행 ID가 이미 있을 때 그 Format, Action, Agent 실행을 기다립니다.
• waitForJob: /v1/jobs/:id의 생성 Job을 기다립니다.
• verifyWebhook: 웹훅 전달의 sume-v1 서명을 확인합니다.

타입이 지정된 오류는 어떻게 동작하나요?

대기 헬퍼는 throw합니다. 폴링 루프에는 결과가 아닌 값을 담을 곳이 없기 때문입니다. 실행 헬퍼는 생성 호출이 거부됐거나 상태 조회가 일시적이지 않은 오류로 실패하면 SumeRunRequestError를, timeout이 먼저 지나면 SumeRunTimeoutError를 throw합니다. waitForJob은 자체 오류인 SumeJobTimeoutError와 SumeJobRequestError를 throw하며, 둘 다 jobId를 담고 있습니다. SumeRunRequestError는 SumeApiError를 확장하므로, 오류 봉투가 code, requestId, retryable, retryAfterSeconds, nextAction, details, 원본 body라는 타입 필드로 들어옵니다.

SumeApiError에는 상태 코드별 하위 클래스도 하나씩 있습니다. SumeAuthenticationError(401), SumeInsufficientCreditsError(402), SumePermissionError(403), SumeNotFoundError(404), SumeConflictError(409), SumeRateLimitError(429), SumeServerError(5xx)입니다. 실행 헬퍼는 이 하위 클래스가 아니라 항상 SumeRunRequestError 자체를 throw하므로, 그 status나 code로 분기하세요.

import { SumeRunRequestError, subscribeFormatRun } from "@sume-com/sdk";

try {
  const run = await subscribeFormatRun({ client, path, body });
} catch (error) {
  if (
    error instanceof SumeRunRequestError &&
    (error.status === 402 || error.code === "insufficient_credits")
  ) {
    return topUpAndAlert(error.requestId); // next_action: "add_funds"
  }
  if (error instanceof SumeRunRequestError) {
    log.error({ code: error.code, requestId: error.requestId, retryable: error.retryable });
  }
  throw error;
}

SDK는 실패한 요청을 어떻게 재시도하나요?

createSumeClient는 기본적으로 408, 429, 5xx와 전송 실패를 지수 백오프와 지터를 적용해 두 번 재시도하며, retry-after를 따릅니다. 이 계층은 maxRetries와 timeout 옵션으로 조정합니다.

• 클라이언트는 POST를 Idempotency-Key가 있을 때만 재시도합니다. 키 없이 다시 보내면 두 번째 실행이 시작되고 과금되기 때문입니다.
• subscribeFormatRun은 키를 대신 생성합니다. 직접 만든 키를 넘기거나, 키를 보내지 않으려면 null을 넘길 수 있습니다.
• waitForRun은 일시적인 조회 실패가 연속 여섯 번 나는 것까지 견딥니다(maxTransientFailures, onTransientError). 상태 조회에서 받은 429나 5xx는 실행이 아니라 조회가 실패했다는 뜻입니다.
• 타임아웃, 종료 상태, Job 헬퍼는 Sume SDK에서 Job과 실행 기다리기에서 다룹니다.