---
title: Overview
description: Current Sume Developer API surface for catalog, jobs, usage, media inputs, and generation workflows.
---

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

```text
https://api.sume.com/v1
```

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](https://www.sume.com/dashboard/api-keys) and send it from a
server-side environment.

```bash
export SUME_API_KEY="sume_live_..."

curl https://api.sume.com/v1/me \
  -H "Authorization: Bearer $SUME_API_KEY"
```

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](/formats) runs an authored recipe in a
sandbox and returns durable media plus JSON in a schema you supply — see
[Structured output](/formats/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`](/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](/agents/run-webhooks);
there is no SSE stream, so progress comes from polling `events_url` (a phase timeline).

```bash
npm install @sume-com/sdk
```

It is a convenience layer, not a second contract — this page and the
[API reference](/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](/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/: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), take the receipt by webhook or poll, and read back media plus schema-shaped JSON. See [Format API](/formats), [Create a run](/formats/call), [Runs and results](/formats/runs), [Errors and spend](/formats/errors), and [Bulk runs](/formats/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 Router | `POST /v1/music-router/generate` | — | Music generation; `sume/music-auto` picks the engine. |
| Music 1.0 | `POST /v1/music-1.0/generate` | `POST /v1/models/sume/music-1.0/runs` | Retiring; 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. See [Scheduled](/agents/actions). |
| 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](/agents/completions). |

See the [API reference](/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.

```text
submit generation (canonical or /models/.../runs)
  -> receive job id
  -> poll /v1/jobs/:id/status
  -> fetch /v1/jobs/:id/result when completed
  -> use media.sume.com artifact URLs
```

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](/workflows/generation-admission) for tier limits,
`generation_limits`, and queue-full behavior.

## OpenAPI

The local docs preview serves a snapshot at:

```text
/api/openapi.json
```

Production serves the live schema at:

```text
https://api.sume.com/reference/json
```

Swagger UI is available from the API service at:

```text
https://api.sume.com/reference
```

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`).