---
title: Sume basics
description: A product map of Sume’s surfaces — Agents, Formats, Models, SDK, Dashboard, and the Developer API.
---

Sume is fundamentally a **video agent** platform. People author and iterate in
chat; partners invoke saved recipes over HTTP. Individual generation tools
(Image, Video, Avatar, TTS, timeline, and more) also exist as HTTP APIs, but the
main partner path is calling a **sandbox Agent / Format** that composes those
tools — not stitching raw model calls yourself.

That composition is why you can ship deliverables a single [Video 1.0](/models/video)
clip cannot: multi-minute host footage, B-roll, voiceover, and timeline assembly
into a **post-ready** video.

For job admission, polling, and `media.sume.com` mechanics, see
[Core concepts](/workflows/core-workflow).

## In a nutshell

- **[Agents](#agents)** — human-in-the-loop authoring at [sume.com/agents](https://www.sume.com/agents)
- **[Formats / Format API](#formats--format-api)** — the primary partner invoke surface
- **[Models](#models)** — atomic generation APIs (supporting building blocks)
- **[Agent Completions / Scheduled](#agent-completions--scheduled)** — ad-hoc and recurring agent runs
- **[SDK](#sdk)** — the TypeScript client around the same Developer API
- **[Dashboard](#dashboard)** — keys, jobs, usage, billing
- **[Developer API + media](#developer-api--media)** — `api.sume.com` and `media.sume.com`
- **[Workspaces](#workspaces)** — where keys and spend resolve

## Agents

[Agents](https://www.sume.com/agents) is the chat UI where a person works with
the sandbox Agent: write a brief, approve spend, inspect artifacts, and shape a
house style over a few turns.

This is where Formats are authored — either by editing a Format in the library
or by asking the Agent in chat to save a recipe (`SKILL.md` plus references).
Interactive chat is the right surface when a human should stay in the loop.

Docs: [Agents overview](/agents) · [Safe automation](/agents/safe-automation)

## Formats / Format API

A **Format** is a saved authoring recipe. Partners call it by handle and slug;
Sume boots a fresh sandbox, loads the recipe, runs the Agent with generation
tools, and returns artifacts plus optional structured JSON.

**This is the surface most partners should integrate.** One HTTP call carries
the judgement and orchestration that would otherwise live in your own glue code.

```text
Format run = fresh sandbox + recipe (SKILL) + instruction/input + tools
           → artifacts + optional structured output
```

Docs: [Format API overview](/formats) · [Calling a Format](/formats/call) ·
[Bulk runs](/formats/bulk-runs) ·
[Cookbook: embed a Format](/cookbooks/embed-a-format)

## Models

**Models** are atomic generation endpoints: create an avatar, render a talking
clip, generate an image or a short video clip, add captions, and so on. They are
real product surfaces — useful when you need one model invocation and nothing
else.

They are **supporting** relative to Formats. A Format decides *which* tools to
call, in what order, and how to assemble the result. If you only need a single
clip or image, call the model; if you need a packaged workflow, call a Format.

Docs: [Models overview](/models) · [Video 1.0](/models/video) ·
[Avatar videos](/models/avatar-videos)

## Agent Completions / Scheduled

Not every agent task is worth saving as a Format.

| Surface | When to use |
|---|---|
| [Agent Completions](/agents/completions) | One-off backend task; nothing worth saving as a recipe |
| [Scheduled](/agents/actions) | The same saved task on a cadence (Actions) |

Both run the Agent; Completions is ad-hoc, Scheduled is recurring. Formats stay
the path when the recipe is fixed and only the inputs change.

## SDK

The [TypeScript SDK](/sdk) is a thin client over the same Developer API for
Node / Bun / Deno / Workers, including [`subscribeFormatRun`](/sdk/runs) so you
do not hand-roll polling. Everything it does is also reachable over plain HTTP.

Two more clients exist and still work, but they are not part of the primary
path today: the [CLI](/cli) for local shells and scripts, and
[hosted MCP](/mcp) for clients that speak remote MCP. Reach for them when your
environment calls for it, not as the default integration.

## Dashboard

The dashboard is the human operator surface for the same workspace the API key
resolves to:

- [API keys](https://www.sume.com/dashboard/api-keys)
- [Jobs](https://www.sume.com/dashboard/jobs)
- [Usage](https://www.sume.com/dashboard/usage)
- [Billing & subscription](https://www.sume.com/dashboard/subscription)
- [Playground](https://www.sume.com/playground)

Docs: [API keys](/dashboard/api-keys) · [Jobs](/dashboard/jobs) ·
[Usage](/dashboard/usage) · [Billing](/dashboard/credits)

## Developer API + media

| Domain | Role |
|---|---|
| `api.sume.com` | Public Developer API (`/v1`) and OpenAPI (`/reference/json`) |
| `media.sume.com` | First-party generated media artifacts |

Keys authenticate; the API is workspace-scoped. Generated outputs that belong
to Sume are returned as `media.sume.com` URLs — that is the public artifact
contract.

Docs: [Public API](/public-api) · [API reference](/api/reference) ·
[Authentication](/authentication) · [Media inputs](/workflows/asset-library)

## Workspaces

API keys and spend resolve to a **workspace**. The key carries that context —
do not send `workspace_id` in request bodies. Team-owned Formats are reachable on
both vanity and opaque paths with a key **created in that team workspace**; a
personal key fails with `403 workspace_key_required` — see
[Team Formats need a team key](/formats/call#team-formats-need-a-team-key).

## What next?

- [Quick start](/) — your first run, in the Agents tab or over the API
- [Format API](/formats) — why Formats exist and how a run works end to end
- [Core concepts](/workflows/core-workflow) — jobs, admission, artifacts, usage