Overview

The Sume Public API is a workspace-scoped interface for server integrations, CLI automation, MCP wrappers, and agent tools. It exposes the same core capabilities used by the Sume app: generation jobs, job polling, Brand DNA, avatars, uploads, and Asset Library scene search.

Base URL

All endpoint paths on this page are relative to that base URL.

Authentication

Send a workspace API key from a server-side environment:

Bearer auth is preferred. Existing dashboard-issued keys may also support the legacy X-Api-Key header, but new integrations should use Authorization: Bearer.

Do not pass workspace_id or user_id in request bodies. Sume derives user and workspace scope from the API key.

Treat API keys, signed upload URLs, storage object keys, and private media URLs as secrets. Do not paste them into prompts, logs, support tickets, or public issue trackers.

Quickstart

1. Create or copy a Sume API key from the API dashboard.
2. Verify the key with GET /me.
3. Check credit capacity with GET /credits.
4. Create an async job, such as POST /videos/generations.
5. Poll GET /jobs/{jobId} until it reaches a terminal state.
6. Fetch GET /jobs/{jobId}/result for generated media or analysis output.

Endpoint map

Area	Endpoints	Use for
Account	GET /me, GET /credits	Verify auth, workspace scope, plan, credits, and active generation capacity.
Brand	GET /brand, GET /brand/current	Read sanitized Brand DNA profiles and current brand context.
Avatars	GET /avatars, GET /avatars/{avatarId}	Pick public or workspace avatars for ads and Face Swap workflows.
Jobs	GET /jobs, GET /jobs/{jobId}, GET /jobs/{jobId}/result	List jobs, poll status, and retrieve generated or analyzed outputs.
Generation	POST /images/generations, POST /videos/generations, POST /ads/videos, POST /face-swap, POST /reference-analysis	Create asynchronous media or analysis jobs. These endpoints may spend credits.
Uploads	POST /uploads/presign, POST /assets	Upload videos and finalize them for Asset Library ingest or feature-specific workflows.
Asset Library	GET /assets, GET /assets/{assetId}	Search indexed scene assets and retrieve reusable clip/source metadata.

Async job lifecycle

Most write endpoints return quickly with a job id. Store that id and poll until the job reaches a terminal state.

Status class	Integration behavior
queued, processing, or another non-terminal status	Continue polling with backoff. Video jobs take longer than image jobs.
completed	Fetch the result and use output URLs or structured result data.
failed, canceled, or expired	Stop polling and surface the sanitized error message.

Example video job:

Example job response shape:

Upload workflow

Use uploads when an endpoint needs user-provided video bytes.

1. Request a temporary upload target with POST /uploads/presign.
2. Upload bytes directly to the returned upload_url using the returned required_headers.
3. For Asset Library ingestion, finalize with POST /assets.
4. For Face Swap, pass the returned media_url to POST /face-swap.

purpose is either asset_library_video or face_swap_source_video. upload_url, object_key, and required_headers are operational values for the upload flow and should not be logged.

Pagination

List endpoints use cursor pagination.

Pass next_cursor back as cursor to continue:

Error envelope

Error responses use a consistent envelope:

Keep request_id for support. Redact API keys, signed URLs, storage object keys, raw private media URLs, user emails, and workspace or user ids from external logs.

Schema and examples

• API reference lists all current endpoints.
• API cookbook gives copy-paste workflow examples.
• The preview OpenAPI snapshot is available at /api/openapi.json.
• Production Sume serves the live schema from https://www.sume.so/api/v1/openapi.json.

For exact request and response fields, treat the OpenAPI schema as the source of truth.