TypeScript SDK

@sume-com/sdk is the official TypeScript client for api.sume.com. It covers every operation in the public OpenAPI schema, plus the helpers every partner otherwise writes by hand: subscribeFormatRun, waitForRun, waitForJob, uploadFile, and verifyWebhook.

Published as @sume-com/sdk@0.2.0, MIT licensed, with no runtime dependencies. It needs fetch and WebCrypto — Node 18+, Bun, Deno, or Cloudflare Workers.

This page is not a method reference. Request and response fields come from the API reference and live OpenAPI (https://api.sume.com/reference/json), which stay the source of truth. What follows is the client-shaped part: the factory, auth, and the helpers that have no REST equivalent.

Create a client

Option	Default	Notes
apiKey	—	Required. A Developer API key from API Keys.
baseUrl	https://api.sume.com	Point at https://api.dev.sume.com for development.
fetch	the runtime's globalThis.fetch	A seam for instrumentation, retries, or tests.

Pass client on every call. Operations accept a module-level default client, but that default is created without a base URL or a key — it is there so the generated code compiles, not so you can skip the factory. Thread the client you made:

Authentication

The client sends x-api-key only. It does not set Authorization, and you should not add one yourself.

The API accepts either header alone (see Authentication), but it rejects both at once: a request carrying Authorization: Bearer and x-api-key together fails 401 unauthorized with Send only one API key credential. There is no precedence rule — neither header wins. So an Authorization header added on top of the client's own — a session token, a gateway's credential, an interceptor you forgot about — fails the request even though x-api-key was correct. If you wrap fetch via the fetch option, make sure your wrapper is not adding one.

Your key needs formats:read and formats:write to run Formats. Scopes are fixed when a key is created and cannot be added later; an older key returns 403 insufficient_scope on every run. Create a new one and rotate.

Team Formats need a team (workspace) key. A personal key calling a team Format fails with 403 workspace_key_required — see Calling a Format.

Server-side only. A Sume API key spends your credits, and there is no browser-safe variant. Never ship one to client JavaScript, a mobile bundle, or a NEXT_PUBLIC_* variable — put your own endpoint in front and construct the Sume request there. The full custody rules are in Embed a Format in your product.

A Format run, end to end

Prefer subscribeFormatRun for Formats: one call creates the run and waits for the terminal receipt. Pair it with run webhooks when you can skip the wait entirely.

What to expect today:

• subscribeFormatRun polls. There is no SSE stream, so onStatus reflects status polling rather than a push feed. For progress detail while you wait, read events_url — a phase timeline, not a log feed. See Watch a run progress.
• Prefer a webhook when delivery is available for your environment: pass communication.webhook_url on create (or skip the wait and handle the push). See Verifying webhooks.
• Default timeout is 20 minutes (video Formats routinely run 10–20). It resolves for any terminal status; it throws only when the create call itself is refused.
• Generated operations do not throw on an API error. They resolve with { data, error, response }. subscribeFormatRun / waitForRun throw, because a poll loop has nowhere to put a non-result.

Use waitForRun when you already have a run id (Action / Agent Completion, or a create you made yourself), and waitForJob for generation jobs — /v1/image-1.0/generate, /v1/video-1.0/generate, the Avatar routes — which live at /v1/jobs/:id and are not runs.

Where to go next

You want	Read
Create + wait (or poll an existing run or job)	Waiting for runs and jobs
Verify a signed webhook delivery	Verifying webhooks
Exact request and response fields	API reference
The whole partner integration	Embed a Format in your product

Scope of this section

These pages document the hand-written surface: the client factory and the helpers. Everything else the package exports is generated from the same OpenAPI schema the API reference describes, one function per operation, named after the operation id — listFormats, createFormatRun, getFormatRunStatus, cancelFormatRun, and so on. Your editor's autocomplete is a better catalog than a copy of the schema would be, so there is not one here.