SDK
Node.js·TypeScript용 @sume-com/client와 Python용 sume-client — 설치하고, api.sume.com을 가리키게 하고, 이미지나 비디오를 만들고, 오류를 처리해 보세요.
이 문서는 영문 원고를 AI로 번역한 내용이라 표현이 어색할 수 있습니다.
Sume는 SDK 두 개를 제공합니다. 둘 다 Image Router와 Video Router로 이미지와 비디오를 만들고, job을 기다린 뒤 결과를 돌려줍니다.
| 언어 | 패키지 | 설치 |
|---|---|---|
| Node.js·TypeScript | @sume-com/client 0.3.0 | npm install @sume-com/client |
| Python | sume-client 0.1.0 | pip install sume-client |
@sume-com/client는 Node.js 18 이상의 서버에서 동작합니다. sume-client는
Python 3.8 이상이 필요합니다.
다루는 범위. 이미지·비디오 생성, job 기다리기, 파일 업로드, 타입이 있는 오류, 그리고 (TypeScript에서는) 웹훅 검증입니다. Format, Action, Agent Completion을 비롯한 나머지 경로에는 SDK 호출이 없습니다. 같은 키로 HTTP를 직접 호출하세요. Format 호출하기, 실행과 결과, API 레퍼런스에 각 요청이 있습니다.
api.sume.com
두 패키지 모두 기본값은 open.sume.com API인 https://api.open.sume.com입니다.
sume.com 워크스페이스를 쓰려면 base URL을 https://api.sume.com으로 지정하세요.
둘 다 SUME_API_KEY에서 키를 읽습니다. API 키에서
만들고 서버에만 두세요.
createSumeClient는 credentials(키), timeout, maxRetries, pollInterval,
maxPollTime도 받습니다. SyncClient와 AsyncClient는 base_url, timeout,
api_key를 받습니다.
클라이언트는 키를 Authorization: Bearer <key>로 보냅니다. x-api-key 헤더를
함께 붙이지 마세요. 두 헤더가 함께 오면 API가 거절합니다
(401 unauthorized, Send only one API key credential.).
서버 전용입니다. Sume API 키는 잔액을 씁니다. @sume-com/client는 브라우저에서
실행을 거부합니다. 클라이언트 JavaScript, 모바일 번들, NEXT_PUBLIC_* 변수에 키를
넣지 마세요. 앞에 자체 엔드포인트를 두고, 그 엔드포인트에서 Sume를 호출하세요.
전체 보관 규칙은 제품에 Format 임베드에 있습니다.
이미지 만들기
subscribe는 제출한 뒤 /v1/jobs/{id}/status를 폴링하고, job이 완료되면
/v1/jobs/{id}/result를 읽습니다.
- TypeScript는
input에model을 담은 라우터 경로(/v1/image-router/generate또는/v1/video-router/generate)나 모델 id를 받습니다. 결과에는status(completed,failed,nsfw,canceled),images,video,artifacts,error가 있습니다. - Python은 모델 id를 받고 결과의
data(result.artifacts)를 돌려줍니다.failed나canceled로 끝난 job은 대신job.error가 담긴 상태 레코드를 돌려줍니다. - 모델 id는 공개 모델 카탈로그(
GET /v1/open/catalog/{id})로 라우팅되므로, 없는 id는 job이 생기기 전에 실패합니다.
비디오 만들기
비디오는 보통 몇 분 걸립니다. TypeScript 클라이언트는 maxPollTime(기본 5분)이
지나면 기다리기를 멈추고 TimeoutError를 던집니다. 그 requestId가 job id이고,
job은 계속 실행됩니다. 긴 job에는 maxPollTime을 늘리거나, 나중에
/v1/jobs/{id}로 읽으세요. Python 클라이언트는 job이 끝날 때까지 기다립니다.
지금 제출하고 나중에 기다리기
SyncClient에는 status(request_id), result(request_id), cancel(request_id)도
있습니다. AsyncClient는 asyncio용으로 같은 메서드를 제공합니다.
TypeScript에서는 withPolling: false를 넘기면 접수되는 즉시 job을 돌려받고,
webhook: { url }을 넘기면 Sume가 결과를 그 엔드포인트로 POST합니다. 그 전달은
웹훅 검증으로 확인하세요.
파일 업로드
모델은 입력 미디어를 URL로 받습니다. 로컬 파일은 먼저 업로드하세요.
각각 POST /v1/files/generate-upload-url에 업로드할 자리를 받고, 바이트를 올린 뒤
파일의 공개 URL을 돌려줍니다. 업로드는 무료입니다.
오류
| TypeScript | Python | 언제 |
|---|---|---|
AuthenticationError | SumeClientError, status_code 401 | 키가 없거나, 틀렸거나, 폐기됨 |
NotEnoughCreditsError | SumeClientError, status_code 402 | 잔액이 가격을 감당하지 못함 |
BadInputError | SumeClientError, status_code 400 | 필드가 없거나 잘못됨 |
APIError | SumeClientError | 그 밖의 거절. statusCode(status_code)와 code를 읽으세요 |
TimeoutError | — | maxPollTime이 지남. job은 계속 실행됨 |
CredentialsMissedError | CredentialsMissedError | 키를 넘기지 않았고 SUME_API_KEY도 없음 |
각 오류에는 API의 code와 request_id(TypeScript는 requestId)가 담깁니다.
코드 목록은 오류와 크레딧에 있습니다.
안전한 재시도. 모든 제출에 Idempotency-Key가 붙으므로, 다시 보낸 제출이
과금되는 두 번째 job을 만들지 않습니다. TypeScript에서는 idempotencyKey로 직접
키를 줄 수 있습니다. 클라이언트는 429와 5xx 응답을 스스로 재시도합니다.
다음 단계
| 하고 싶은 일 | 읽을 문서 |
|---|---|
| job, 또는 Format·Action·Agent 실행 기다리기 | 실행과 Job 기다리기 |
| 서명된 웹훅 전달 확인 | 웹훅 검증 |
| 정확한 요청·응답 필드 | API 레퍼런스 |
| 파트너 통합 전체 | 제품에 Format 임베드 |