---
title: TypeScript SDK
description: @sume-com/sdk — 설치하고, 클라이언트를 만들고, 인증한 뒤 Node·Bun·Deno·Workers에서 Format을 끝까지 실행해 보세요.
---

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

```bash
npm install @sume-com/sdk
```

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

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

## 클라이언트 만들기

```ts
import { createSumeClient } from "@sume-com/sdk";

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

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

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

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

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

## 인증

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

API는 두 헤더를 각각 하나씩은 받지만([인증](/authentication) 참고), **동시에 보내면
거부합니다.** `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 호출하기](/formats/call#team-formats-need-a-team-key)에서 살펴보세요.

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

## Format 실행, 처음부터 끝까지

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

```ts
import { createSumeClient, subscribeFormatRun } from "@sume-com/sdk";

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

const run = await subscribeFormatRun({
  client,
  path: { handle: "acme", slug: "product-promo" },
  idempotencyKey: "order-8823-promo-v1",
  body: {
    input: { product_url: "https://shop.example.com/p/8823" },
    generation_spend_cap_usd: 3,
  },
  onStatus: (status, snapshot) => console.log(status, snapshot.next_action),
});

if (run.status === "completed") {
  console.log(run.primary_output_url);
}
```

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

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

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

## 다음으로 볼 문서

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

## 이 섹션의 범위

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