Reference
Client libraries
@sume-com/client (Node.js 18+) and sume-client (Python 3.8+) submit a job, poll it and return the result in one call, with idempotent retries and typed errors. Server-side only.
Install
npm install @sume-com/clientConfigure
Pass this API's base URL, https://api.sume.com, as the examples below do. Both libraries read the key from SUME_API_KEY. The JavaScript client refuses to load in a browser.
import { createSumeClient } from "@sume-com/client";
export const sume = createSumeClient({
credentials: process.env.SUME_API_KEY,
baseURL: "https://api.sume.com",
maxPollTime: 600_000,
});Generate
subscribe sends an Idempotency-Key, polls the job and reads the result. In JavaScript it takes the router path with model in the input, and a failed job resolves with status: "failed" and its error. In Python it takes the model id; a failed job returns its status record with job.error.
const image = await sume.subscribe("/v1/image-router/generate", {
input: { model: "gpt-image-2", prompt: "A red kite over a beach", quality: "low" },
});
console.log(image.images?.[0]?.url);If the wait runs out
A TimeoutError means your maxPollTime passed, not that the job stopped. Call subscribe again with the same input and idempotencyKey: error.idempotencyKey: you get the same job, charged once.
Upload a file
import { readFile } from "node:fs/promises";
const imageUrl = await sume.uploadImage(await readFile("cup.png"), "png");
const audioUrl = await sume.upload(await readFile("speech.wav"), "audio/wav");Errors
| Class | When |
|---|---|
AuthenticationError | 401: missing or wrong key. |
NotEnoughCreditsError | 402: the balance cannot cover the price. |
BadInputError | 400: a field is wrong; details lists each one. |
APIError | Any other status, with statusCode, code and requestId. |
TimeoutError | The local wait ran out; carries requestId and idempotencyKey. |
In Python every API refusal is a SumeClientError with status_code, code, request_id and details.