Overview

The Sume Developer API is the public server-side API for api.sume.com. It is workspace-scoped, key-authenticated, and designed for generation workflows that need durable jobs, public media artifacts, usage tracking, and dashboard observability.

Base URL

All endpoint paths on this page include /v1 because the live OpenAPI schema is served from the API service root.

Product, API, and media domains

Domain / URL	Purpose
`https://www.sume.com`	Public company/product site.
`https://www.sume.com/dashboard`	Dashboard home.
`https://www.sume.com/dashboard/api-keys`	Create and manage Developer API keys.
`https://www.sume.com/dashboard/jobs`	Inspect jobs.
`https://www.sume.com/dashboard/usage`	Usage and balance summary.
`https://www.sume.com/dashboard/subscription`	Billing & subscription (plans and credit top-ups).
`https://www.sume.com/pricing/api`	Public metered API rate card (source of truth for prices).
`https://www.sume.com/playground`	Avatar playground (human experiments).
`https://www.sume.com/agents`	Agents product surface.
`https://api.sume.com/v1`	Public Developer API.
`https://api.sume.com/reference`	Swagger UI.
`https://api.sume.com/reference/json`	Live OpenAPI JSON (schema source of truth).
`https://media.sume.com`	First-party media and artifact URLs returned by completed jobs.

Authentication

Create an API key in the API Keys dashboard and send it from a server-side environment.

The API also accepts x-api-key: sume_live_.... Do not send workspace or user identifiers in request bodies; Sume resolves scope from the API key.

Start with the Format API

Most partner integrations are one call to a saved recipe, not a hand-rolled chain of model invocations. Format API runs an authored recipe in a sandbox and returns durable media plus JSON in a schema you supply — see Structured output.

The model endpoints below are the layer underneath. Call them directly when you want exactly one model invocation and own the orchestration yourself.

TypeScript clients

From Node, Bun, Deno, or Workers, @sume-com/sdk (@sume-com/sdk@0.2.0) wraps every operation on this page with types generated from the same OpenAPI schema, and adds the helpers this API otherwise makes you write: subscribeFormatRun (Format create + wait), waitForRun, waitForJob (generation jobs), uploadFile, and verifyWebhook. Lead with subscribeFormatRun + webhooks; there is no SSE stream, so progress comes from polling events_url (a phase timeline).

It is a convenience layer, not a second contract — this page and the API reference stay the source of truth for fields.

Current endpoint map

This table is a navigational summary only. Exact request/response schemas come from live OpenAPI (https://api.sume.com/reference/json). Prefer the readable API reference for method/path notes, and model guides for workflow prose — do not treat duplicated Markdown tables as a second schema.

Prefer canonical product paths (/v1/{family}-1.0/...) for new integrations. /v1/models/sume/.../runs aliases remain supported for compatibility.

Area	Canonical	Compatibility / aliases	Use for
Formats	`GET /v1/formats`, `GET /v1/formats/:id`, `POST /v1/formats/:id/runs`, `POST /v1/formats/:id/bulk-runs`, `GET /v1/formats/:handle/:slug`, `POST /v1/formats/:handle/:slug/runs`, `POST /v1/formats/:handle/:slug/bulk-runs`, `GET /v1/format-run-queues/:id`, `GET /v1/format-runs/:id`, `GET /v1/format-runs/:id/status`, `GET /v1/format-runs/:id/result`, `POST /v1/format-runs/:id/cancel`	—	Run an authored recipe (one run, or a bulk queue) and read back media plus schema-shaped JSON. See Format API and Bulk runs.
Health	`GET /v1/health`	—	Service readiness checks.
Catalog	`GET /v1/catalog`	—	Discover capabilities, models, runtime readiness, and pricing metadata.
Account	`GET /v1/me`	—	Verify the API key and resolved workspace context.
Balance and usage	`GET /v1/balance`, `GET /v1/usage`	—	Read USD balance and usage ledger entries.
Jobs	`GET /v1/jobs`, `GET /v1/jobs/:id`, `GET /v1/jobs/:id/status`, `GET /v1/jobs/:id/result`, `POST /v1/jobs/:id/cancel`, `GET /v1/jobs/:id/events`	—	List, inspect, poll, cancel, recover, and audit jobs.
Avatar 1.0	`POST /v1/avatar-1.0/generate`, `POST /v1/avatar-1.0/talking-video`, `GET /v1/avatar-1.0/avatars`, `GET /v1/avatar-1.0/avatars/:id`	`POST /v1/models/sume/avatar/v1.0/runs`, `POST /v1/models/sume/avatar-1.0/generate/runs`, `POST /v1/models/sume/avatar-1.0/talking-video/runs`, `GET /v1/avatars`, `GET /v1/avatars/:id`	Create and read avatars / talking videos.
Avatar Video 1.0	`GET /v1/avatar-videos`, `GET /v1/avatar-videos/:id`	`POST /v1/models/sume/avatar-video/v1.0/runs`	Product/scene avatar-video runs and resource reads.
Avatar Video Previews	`POST /v1/avatar-video-previews`, `GET /v1/avatar-video-previews/:id`, `POST /v1/avatar-video-previews/:id/regenerate`, `POST /v1/avatar-video-previews/:id/generate-video`	—	Preview → generate-video flow.
Avatar catalog	`POST /v1/avatar-catalog/search`	—	Search reusable catalog avatars.
Avatar Face Swap (Beta)	—	`POST /v1/models/sume/avatar-face-swap/v1.0/runs`	Face-swap model runs.
Image 1.0	`POST /v1/image-1.0/generate`	`POST /v1/models/sume/image-1.0/runs`	Image generation.
Video 1.0	`POST /v1/video-1.0/generate`	`POST /v1/models/sume/video-1.0/runs`	Video generation.
Music 1.0	`POST /v1/music-1.0/generate`	`POST /v1/models/sume/music-1.0/runs`	Music generation.
Video captions	`POST /v1/video-captions`, `GET /v1/video-captions/:id`	—	Caption jobs and resource reads.
Trending videos	`POST /v1/trending-videos/search`	—	Search TikTok trending video metadata.
Actions	`GET /v1/actions`, `GET /v1/actions/:id`, `POST /v1/actions/:id/runs`, `GET /v1/action-runs/:id`, `POST /v1/action-runs/:id/cancel`	—	Recurring schedules. See Scheduled.
Agent Completions	`POST /v1/agent/completions`, `GET /v1/agent-runs`, `GET /v1/agent-runs/:id`, `POST /v1/agent-runs/:id/cancel`	—	Run the Agent on an ad-hoc task. See Agent Completions.

See the API reference for the full method/path tables and OpenAPI hide-list notes.

Older www.sume.so consumer-product routes such as /credits, /uploads/presign, /brand, /ads/videos, /face-swap, and /reference-analysis are not part of the current sume.com developer platform API.

Internal voice capabilities, raw provider model ids, and provider task URLs are not public API surfaces unless they appear in /v1/catalog and the OpenAPI schema.

Job-first workflow

Model-run and compatibility submit endpoints accept work, create a job, and return a response you can poll or recover later.

Most integrations should store the job id and poll with backoff. Use webhooks when you have a public HTTPS callback endpoint and want Sume to notify your server on terminal job events.

Paid generation uses queue-first admission. Workspace concurrency limits apply to jobs that are actively processing; valid submissions can still be accepted as queued while queue capacity remains. See Generation admission for tier limits, generation_limits, and queue-full behavior.

OpenAPI

The local docs preview serves a snapshot at:

Production serves the live schema at:

Swagger UI is available from the API service at:

Use the live schema as the exact request/response source of truth. The docs repo snapshot is refreshed from that endpoint (see README / pnpm openapi:sync).