TypeScript SDK

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

The published package is @sume-com/sdk@0.2.0. It has an MIT license and no runtime dependencies. It needs fetch and WebCrypto: Node 18+, Bun, Deno, or Cloudflare Workers.

This page is not a method reference. The request and response fields come from the API reference and the live OpenAPI (https://api.sume.com/reference/json). These two stay the source of truth. This page gives the client 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	Use https://api.dev.sume.com for development.
fetch	the runtime's globalThis.fetch	Supply your own function for instrumentation, retries, or tests.

Pass client on every call. Operations accept a default client at the module level. But that default targets https://api.sume.com with no key. It is there only so that the generated code compiles. It does not let you skip the factory. Pass the client that you made:

Authentication

The client sends x-api-key only. It does not set Authorization. Do not add that header yourself.

The API accepts each header alone (refer to Authentication). But it rejects both at once. A request that has Authorization: Bearer and x-api-key together fails with 401 unauthorized and Send only one API key credential. There is no precedence rule. Neither header wins.

Thus, an Authorization header in addition to the header of the client causes the request to fail, even when x-api-key is correct. That extra header can come from a session token, the credential of a gateway, or an interceptor that you forgot. If you wrap fetch through the fetch option, make sure that your wrapper does not add one.

Your key needs formats:read and formats:write to run Formats. The scopes of a key are fixed when you create the key. You cannot add scopes later. An older key returns 403 insufficient_scope on every run. Create a new key and rotate the old key.

Team Formats need a team (workspace) key. If a personal key calls a team Format, the call fails with 403 workspace_key_required. Refer to Calling a Format.

Server-side only. A Sume API key spends your credits. There is no browser-safe variant. Never put a key in client JavaScript, a mobile bundle, or a NEXT_PUBLIC_* variable. Put your own endpoint in front, and make the Sume request from that endpoint. Embed a Format in your product gives the full custody rules.

A Format run, end to end

For Formats, prefer subscribeFormatRun. One call creates the run and waits for the terminal receipt. If you can skip the wait fully, use it together with run webhooks.

What to expect today:

• subscribeFormatRun polls. There is no SSE stream. Thus, onStatus shows the result of status polls, not a push feed. For progress detail while you wait, read events_url. It is a phase timeline, not a log feed. Refer to 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). Refer to Verifying webhooks.
• Default timeout is 20 minutes (video Formats usually run 10–20). It resolves for each terminal status. It throws SumeRunRequestError when the API refuses the create call or when a status read has a non-transient failure. It throws SumeRunTimeoutError when the timeout occurs first.
• Generated operations do not throw on an API error. They resolve with { data, error, response }. subscribeFormatRun / waitForRun throw, because a poll loop has no place to put a non-result.

When you already have a run id, use waitForRun. The run id can come from Action / Agent Completion, or from a create that you made yourself. For generation jobs, use waitForJob. These jobs come from /v1/image-1.0/generate, /v1/video-1.0/generate, and the Avatar routes. They 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. A generator makes all other exports of the package from the same OpenAPI schema that the API reference describes. There is one function for each operation. The name of each function is the operation id: listFormats, createFormatRun, getFormatRunStatus, cancelFormatRun, and others.

The autocomplete of your editor is a better catalog than a copy of the schema. Thus, this page does not have a copy.