TypeScript SDK

이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.

@sume-com/sdk는 api.sume.com의 공식 TypeScript 클라이언트입니다. 공개 OpenAPI 스키마의 모든 오퍼레이션을 다루고, 파트너가 직접 손으로 짜게 되는 헬퍼도 함께 제공합니다. subscribeFormatRun, waitForRun, uploadFile, verifyWebhook이 그것입니다.

@sume-com/sdk@0.2.0으로 배포되며 MIT 라이선스이고 런타임 의존성이 없습니다. fetch와 WebCrypto가 필요하므로 Node 18 이상, Bun, Deno, Cloudflare Workers에서 동작합니다.

이 페이지는 메서드 레퍼런스가 아닙니다. 요청과 응답 필드는 API 레퍼런스와 라이브 OpenAPI(https://api.sume.com/reference/json)에서 오며, 그쪽이 원본입니다. 여기서는 클라이언트 쪽 이야기, 즉 팩토리와 인증, 그리고 REST에 대응물이 없는 헬퍼를 다룹니다.

클라이언트 만들기

옵션기본값설명
apiKey—필수입니다. API Keys에서 발급한 Developer API 키입니다.
baseUrlhttps://api.sume.com개발 환경에서는 https://api.dev.sume.com을 지정하세요.
fetch런타임의 globalThis.fetch계측, 재시도, 테스트를 끼워 넣는 지점입니다.

모든 호출에 client를 넘기세요. 오퍼레이션은 모듈 수준의 기본 클라이언트를 받지만, 그 기본값은 베이스 URL도 키도 없이 만들어집니다. 생성된 코드가 컴파일되게 하려고 있는 것이지 팩토리를 건너뛰라는 뜻이 아닙니다. 직접 만든 클라이언트를 넘기세요.

인증

클라이언트는 x-api-key만 보냅니다. Authorization은 설정하지 않으며, 직접 추가해서도 안 됩니다.

API는 두 헤더를 각각 하나씩은 받지만(인증 참고), 동시에 보내면 거부합니다. Authorization: Bearer와 x-api-key를 함께 실은 요청은 Send only one API key credential. 메시지와 함께 401 unauthorized로 실패합니다. 우선순위 규칙은 없으며 어느 쪽도 이기지 않습니다. 그래서 클라이언트가 보내는 키 위에 Authorization 헤더가 얹히면 — 세션 토큰, 게이트웨이 자체 자격 증명, 잊고 있던 인터셉터 등 — x-api-key가 맞았는데도 요청이 실패합니다. fetch 옵션으로 fetch를 감쌌다면 래퍼가 이 헤더를 추가하지 않는지 확인하세요.

Format을 실행하려면 키에 formats:read와 formats:write가 필요합니다. 스코프는 키를 만들 때 고정되며 나중에 추가할 수 없습니다. 예전 키는 실행할 때마다 403 insufficient_scope를 반환하니 새로 만들어 교체하세요.

팀 Format에는 팀(워크스페이스) 키가 필요합니다. 개인 키로 팀 Format을 호출하면 403 workspace_key_required로 실패합니다. Format 호출하기에서 살펴보세요.

서버 전용입니다. Sume API 키는 크레딧을 소모하며, 브라우저에 안전한 변형은 없습니다. 클라이언트 JavaScript, 모바일 번들, NEXT_PUBLIC_* 변수에 절대 넣지 마세요. 앞단에 자체 엔드포인트를 두고 거기서 Sume 요청을 구성하세요. 전체 보관 규칙은 제품에 Format 임베드하기에 있습니다.

Format 실행, 처음부터 끝까지

Format에는 **subscribeFormatRun**을 권장합니다. 한 번의 호출로 실행을 만들고 종료 영수증까지 기다립니다. 기다림을 아예 건너뛸 수 있다면 run 웹훅과 함께 쓰세요.

오늘 기준으로 알아둘 점입니다.

  • subscribeFormatRun은 폴링합니다. 아직 SSE 이벤트 스트림이 없어서 onStatus는 로그 피드가 아니라 상태 폴링을 반영합니다. 분기할 만한 필드는 next_action입니다 (poll_status vs fix_input). 기다리는 동안 진행 상황을 더 보고 싶다면 timeline: true를 넘기세요 — Format run의 phase 타임라인 (events_url)이 snapshot.timeline으로 함께 옵니다. run 진행 상황 보기를 참고하세요.
  • 환경에서 전달이 가능하다면 웹훅을 권장합니다. 생성할 때 communication.webhook_url을 넘기거나, 기다림을 건너뛰고 푸시를 처리하세요. 웹훅 검증에서 살펴보세요.
  • 기본 타임아웃은 20분입니다(비디오 Format은 보통 10~20분 걸립니다). 어떤 종료 상태든 resolve되고, 생성 호출 자체가 거부될 때만 throw합니다.
  • 생성된 오퍼레이션은 API 오류에 throw하지 않습니다. { data, error, response }로 resolve합니다. subscribeFormatRun / waitForRun은 throw하는데, 폴링 루프에는 결과가 아닌 값을 담을 곳이 없기 때문입니다.

이미 run id가 있다면(Action / Agent Completion이거나 직접 만든 실행) waitForRun을 사용하세요.

다음으로 볼 문서

하려는 일읽을 문서
생성 후 대기(또는 기존 실행 폴링)실행 기다리기
서명된 웹훅 전달 검증웹훅 검증
정확한 요청·응답 필드API 레퍼런스
파트너 연동 전체제품에 Format 임베드하기

이 섹션의 범위

이 페이지들은 손으로 작성한 표면, 즉 클라이언트 팩토리와 헬퍼를 다룹니다. 패키지가 내보내는 나머지는 모두 API 레퍼런스가 설명하는 같은 OpenAPI 스키마에서 생성되며, 오퍼레이션 하나당 함수 하나가 오퍼레이션 id를 따라 이름 붙습니다. listFormats, createFormatRun, getFormatRunStatus, cancelFormatRun 같은 식입니다. 스키마 사본을 여기에 두는 것보다 에디터의 자동완성이 더 나은 카탈로그이므로 목록은 싣지 않았습니다.