Overview

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

Base URL

All endpoint paths on this page include /v1, because the API service root serves the live OpenAPI schema.

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`	Examine 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 that completed jobs return.

Authentication

Create an API key in the API Keys dashboard. Send the key 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 the scope from the API key.

Start with the Format API

Most partner integrations are one call to a saved recipe, not a chain of model invocations that you write yourself. Format API runs an authored recipe in a sandbox. It returns durable media and JSON in a schema that you supply. Refer to Structured output.

The model endpoints below are the layer below the Format API. Call them directly when you want only one model invocation and you control the orchestration yourself.

TypeScript clients

From Node, Bun, Deno, or Workers, @sume-com/sdk (@sume-com/sdk@0.2.0) wraps each operation on this page with generated types from the same OpenAPI schema. It also adds the helpers that you must otherwise write yourself: subscribeFormatRun (Format create + wait), waitForRun, waitForJob (generation jobs), uploadFile, and verifyWebhook. Start with subscribeFormatRun + webhooks. There is no SSE stream. Thus, you get the progress when you poll events_url (a phase timeline).

The SDK 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 only a navigation summary. The accurate request/response schemas come from live OpenAPI (https://api.sume.com/reference/json). For method/path notes, we recommend the readable API reference. For workflow prose, we recommend the model guides. Do not use duplicated Markdown tables as a second schema.

For new integrations, we recommend canonical product paths (/v1/{family}-1.0/...). Sume continues to support the /v1/models/sume/.../runs aliases for compatibility.

Area	Canonical	Compatibility / aliases	Use for
Formats	`GET /v1/formats`, `GET /v1/formats/:handle/:slug`, `POST /v1/formats/:handle/:slug/runs`, `GET /v1/formats/:handle/:slug/runs`, `POST /v1/formats/:handle/:slug/bulk-runs`, `GET /v1/format-runs/:id`, `GET /v1/format-runs/:id/status`, `GET /v1/format-runs/:id/result`, `GET /v1/format-runs/:id/events`, `POST /v1/format-runs/:id/cancel`, `POST /v1/format-runs/:id/webhook/redeliver`, `GET /v1/format-run-queues/:id`	`GET /v1/formats/:id`, `POST /v1/formats/:id/runs`, `POST /v1/formats/:id/bulk-runs` (opaque `skl_…` twins)	Run a saved recipe (one run, or a bulk queue). Get the receipt by webhook or poll. Read the media and the schema-shaped JSON. Refer to Format API, Create a run, Runs and results, Errors and spend, and Bulk runs.
Health	`GET /v1/health`	—	Service readiness checks.
Catalog	`GET /v1/catalog`	—	Find capabilities, models, runtime readiness, and price metadata.
Account	`GET /v1/me`	—	Make sure that the API key works, and get the resolved workspace context.
Balance and usage	`GET /v1/balance`, `GET /v1/usage`	—	Read the USD balance and the 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 Router	`POST /v1/music-router/generate`	—	Music generation. `sume/music-auto` selects the engine.
Music 1.0	`POST /v1/music-1.0/generate`	`POST /v1/models/sume/music-1.0/runs`	Sume will retire it. It resolves through Music Router.
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. Refer to 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. Refer to Agent Completions.

For the full method/path tables and the OpenAPI hide-list notes, refer to the API reference.

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

Internal voice capabilities, raw provider model IDs, and provider task URLs are not public API surfaces, unless they are 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 that you can poll or recover later.

We recommend that most integrations store the job ID and poll with backoff. Use webhooks if you have a public HTTPS callback endpoint. With webhooks, Sume sends terminal job events to your server.

Paid generation uses queue-first admission. Workspace concurrency limits are applicable to jobs that are in the processing state. While the queue has capacity, Sume can still accept valid submissions as queued. For tier limits, generation_limits, and queue-full behavior, refer to Generation admission.

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 accurate source of truth for requests and responses. A sync refreshes the docs repo snapshot from that endpoint (refer to README / pnpm openapi:sync).