SDKs
@sume-com/client for Node.js and TypeScript and sume-client for Python: install, point them at api.sume.com, generate an image or a video, and handle errors.
Sume ships two SDKs. Both generate images and video through the Image Router and Video Router, wait for the job, and return the result.
| Language | Package | Install |
|---|---|---|
| Node.js and 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 runs on the server with Node.js 18 or newer. sume-client
needs Python 3.8 or newer.
What they cover. Image and video generation, the job wait, file uploads, typed errors, and (in TypeScript) webhook verification. Formats, Actions, Agent Completions and every other route have no SDK call. Call them over HTTP with the same key: Calling a Format, Runs and results and the API reference have each request.
api.sume.com
Both packages default to https://api.open.sume.com, the open.sume.com API. To use
your sume.com workspace, set the base URL to https://api.sume.com.
Both read the key from SUME_API_KEY. Make one on
API Keys and keep it on your server.
createSumeClient also takes credentials (the key), timeout, maxRetries,
pollInterval and maxPollTime. SyncClient and AsyncClient take base_url,
timeout and api_key.
Each client sends the key as Authorization: Bearer <key>. Do not add an
x-api-key header as well: the API refuses a request that carries both
(401 unauthorized, Send only one API key credential.).
Server-side only. A Sume API key spends your balance. @sume-com/client refuses
to run in a browser. Never put a key in client JavaScript, a mobile bundle, or a
NEXT_PUBLIC_* variable. Put your own endpoint in front, and call Sume from that
endpoint. Embed a Format in your product
gives the full custody rules.
Generate an image
subscribe submits, polls /v1/jobs/{id}/status, and reads
/v1/jobs/{id}/result once the job completes.
- TypeScript takes a router path (
/v1/image-router/generateor/v1/video-router/generate) withmodelininput, or a bare model id. It resolves withstatus(completed,failed,nsfw,canceled),images,video,artifactsanderror. - Python takes a model id and returns the result's
data(result.artifacts). A job that endsfailedorcanceledreturns its status record instead, withjob.error. - A model id is routed through the public model catalog
(
GET /v1/open/catalog/{id}), so an unknown id fails before any job is made.
Generate a video
Video usually takes minutes. The TypeScript client stops waiting after
maxPollTime (5 minutes by default) and throws TimeoutError, whose requestId is
the job id: the job keeps running. Raise maxPollTime for long jobs, or read the
job later at /v1/jobs/{id}. The Python client waits until the job ends.
Submit now, wait later
SyncClient also has status(request_id), result(request_id) and
cancel(request_id). AsyncClient has the same methods for asyncio.
In TypeScript, pass withPolling: false to get the job back as soon as it is
accepted, and webhook: { url } to have Sume POST the outcome to your endpoint.
Verifying webhooks checks that delivery.
Upload a file
A model takes input media by URL. Upload a local file first:
Each one asks POST /v1/files/generate-upload-url for a place, uploads the bytes,
and returns the file's public URL. Uploading is free.
Errors
| TypeScript | Python | When |
|---|---|---|
AuthenticationError | SumeClientError, status_code 401 | The key is missing, wrong or revoked. |
NotEnoughCreditsError | SumeClientError, status_code 402 | The balance cannot cover the price. |
BadInputError | SumeClientError, status_code 400 | A field is missing or wrong. |
APIError | SumeClientError | Any other refusal. Read statusCode (status_code) and code. |
TimeoutError | — | maxPollTime passed. The job keeps running. |
CredentialsMissedError | CredentialsMissedError | No key was passed and SUME_API_KEY is unset. |
Each error carries the API's code and request_id (requestId in TypeScript).
Errors and credits lists the codes.
Safe retries. Every submit carries an Idempotency-Key, so a retried submit
never makes a second, billed job. In TypeScript, pass idempotencyKey to use your
own. The clients retry 429 and 5xx answers by themselves.
Where to go next
| You want | Read |
|---|---|
| Wait for a job, or for a Format, Action or Agent run | 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 |