Sume API OpenAPI spec: download it, browse it, generate a client

The Sume API's OpenAPI spec is served live at https://api.sume.com/reference/json, and the same API is browsable in Swagger UI at api.sume.com/reference. Download it with one curl and treat it as the exact source of truth for request and response fields, whether you use the official TypeScript SDK or generate a client of your own.

The URLs and rules below come from Sume's API reference and Developer API overview docs and from the schema itself, read on 2026-09-26.

Where do I download the Sume OpenAPI spec?

Fetch the live schema. The API reference's download command is one line, and GET /v1/openapi.json is also one of the few /v1 routes that need no API key.

curl https://api.sume.com/reference/json \
  -o sume-openapi.json

Is the OpenAPI spec or the docs the source of truth?

The spec. The API reference page calls itself a human-readable route map, not a second schema, and warns that its Markdown tables can lag; exact JSON shapes, enums, and required fields come from the live OpenAPI document. The document is OpenAPI 3.0.3 and states two rules every client needs:

• Authenticate with x-api-key or Authorization: Bearer, and send exactly one. A request carrying both is rejected with 401 unauthorized. How Sume API keys work covers scopes and rotation.
• Error code values always match ^[a-z0-9_]+$. Switch on code; message is written for humans and may be reworded.

Which client library does Sume publish?

The official TypeScript client, @sume-com/sdk, is generated from the same schema: one function per operation, named after the operation id, with hand-written helpers on top. The docs call it a convenience layer, not a second contract. The Sume TypeScript SDK quickstart covers it.

For other languages, the docs' answer is plain HTTP: any HTTP client can run the submit, poll, and result loop. Their Kotlin sketch adds that Sume does not publish a Kotlin package.

How do I generate a client from the spec?

Point an OpenAPI 3.0 code generator for your language at the downloaded file. Every operation carries an operationId, such as createVideoGeneration or getApiJob, which is what the TypeScript SDK uses as its function names. Then handle what a generator cannot know:

• Hidden routes are not in the spec. Some implemented routes, such as the asset upload family, the admission preview, and the generic /v1/models/{model_owner}/{model_name}/{model_version}/runs template, are omitted on purpose; do not build on them until they appear in the live schema. For media, the docs say to prefer public HTTPS URLs in generation requests.
• Some statuses are undeclared. The schedule run route, POST /v1/actions/{action_id}/runs, declares 200, 202, 400, 401, 403, 404, 409, 413, 429, and 500, but a 503 raised by the upstream layer is not in that set, so a generated client may not model it.
• Some operations are labeled in their summaries, such as the Avatar Face Swap 1.0 model run marked Beta. Check availability and beta in GET /v1/catalog before you build on one.

What do I still write by hand without the SDK?

The SDK's helpers have no REST equivalent, so a generated client leaves them to you:

• A wait loop. Submit with mode: "async" and an Idempotency-Key, poll GET /v1/jobs/{id}/status honoring next_poll_after_seconds, stop when terminal is true, and read /result once result_ready is true. The deadline is client-side; the docs call 20 minutes reasonable for video.
• Webhook verification. Sume signs HMAC-SHA256 over <timestamp>.<raw_body> and sends sume-v1=<hex> in x-sume-webhook-signature. Verify the raw body before parsing, reject a timestamp outside your replay window, and accept the delivery when any sume-v1= entry matches: during a secret rotation the header carries one per live secret. Signed webhooks for video runs has the full scheme.