---
title: API reference
description: Route map, authentication notes, and response patterns for the current Sume Developer API.
---

This page is a **human-readable route map** for the Sume Developer API. It is
not a second schema. For exact JSON request/response shapes, enums, and field
requirements, use the live OpenAPI document — Markdown tables here can lag.

## OpenAPI schema

Local docs snapshot:

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

Live schema (source of truth for this docs snapshot):

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

Download it:

```bash
curl https://api.sume.com/reference/json \
  -o sume-openapi.json
```

Refresh the checked-in snapshot locally:

```bash
pnpm openapi:sync
# or: node scripts/sync-openapi.mjs
```

## Authentication

All `/v1` API endpoints require a Sume API key except health checks.

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

`x-api-key: $SUME_API_KEY` is also accepted. API responses never return the full
secret key.

## Account, catalog, and usage

| Method | Path | Notes |
|---|---|---|
| `GET` | `/v1/health` | Versioned API health. |
| `GET` | `/v1/catalog` | Available capabilities, endpoints, runtime readiness, models, and pricing metadata. |
| `GET` | `/v1/me` | Current API key, owner, and workspace context. |
| `GET` | `/v1/balance` | USD-denominated available balance. |
| `GET` | `/v1/usage` | Usage ledger entries such as reservations, captures, refunds, and top-ups. |

## Jobs

| Method | Path | Notes |
|---|---|---|
| `GET` | `/v1/jobs` | List workspace jobs, filterable by status/type. |
| `GET` | `/v1/jobs/:id` | Read the public job envelope. |
| `GET` | `/v1/jobs/:id/status` | Lightweight status read for polling. |
| `GET` | `/v1/jobs/:id/result` | Completed result payload, including public artifact URLs when available. |
| `POST` | `/v1/jobs/:id/cancel` | Request cancellation for queued or processing jobs. |
| `GET` | `/v1/jobs/:id/events` | Public timeline events for debugging and recovery. |

Terminal job statuses are `completed`, `failed`, and `canceled`. Non-terminal
statuses are `queued` and `processing`.

## Media inputs

Generation requests accept fetchable public HTTPS media URLs directly in the
fields documented by the live OpenAPI schema (for example Avatar photo
`input.image_url`, Avatar Video `product_image` / `scene.image_url`).

Localhost, private-network, non-HTTPS, and non-image responses are rejected
before generation submission. First-party upload helpers are **not** the default
public API path for normal integrations (see [Hidden from public OpenAPI](#hidden-from-public-openapi)).

## Canonical generation paths

Prefer these product-style endpoints for new integrations.

| Method | Path | Family | Notes |
|---|---|---|---|
| `POST` | `/v1/avatar-1.0/generate` | Avatar 1.0 | Canonical avatar create. |
| `POST` | `/v1/avatar-1.0/talking-video` | Avatar 1.0 | Canonical talking-video create. |
| `GET` | `/v1/avatar-1.0/avatars` | Avatar 1.0 | List Avatar 1.0 avatars. |
| `GET` | `/v1/avatar-1.0/avatars/:id` | Avatar 1.0 | Read one Avatar 1.0 avatar. |
| `POST` | `/v1/image-1.0/generate` | Image 1.0 | Canonical image generate. |
| `POST` | `/v1/video-1.0/generate` | Video 1.0 | Canonical video generate. |
| `POST` | `/v1/music-1.0/generate` | Music 1.0 | Canonical music generate. |

## Compatibility model-run aliases

These `/v1/models/sume/.../runs` paths remain in the public OpenAPI and continue
to work. Prefer the canonical paths above when both exist.

| Method | Path | Public model | Notes |
|---|---|---|---|
| `POST` | `/v1/models/sume/avatar/v1.0/runs` | `sume/avatar/v1.0` | Legacy Avatar 1.0 create. |
| `POST` | `/v1/models/sume/avatar-1.0/generate/runs` | `sume/avatar-1.0/generate` | Alias of Avatar 1.0 generate. |
| `POST` | `/v1/models/sume/avatar-1.0/talking-video/runs` | `sume/avatar-1.0/talking-video` | Alias of Avatar 1.0 talking video. |
| `POST` | `/v1/models/sume/avatar-video/v1.0/runs` | `sume/avatar-video/v1.0` | Legacy Avatar Video 1.0 create. |
| `POST` | `/v1/models/sume/avatar-face-swap/v1.0/runs` | `sume/avatar-face-swap/v1.0` | Avatar Face Swap 1.0 Beta. |
| `POST` | `/v1/models/sume/image-1.0/runs` | `sume/image-1.0` | Alias of Image 1.0 generate. |
| `POST` | `/v1/models/sume/video-1.0/runs` | `sume/video-1.0` | Alias of Video 1.0 generate. |
| `POST` | `/v1/models/sume/music-1.0/runs` | `sume/music-1.0` | Alias of Music 1.0 generate. |

Submit endpoints support the common communication fields `mode`,
`webhook_url`, and `wait_timeout_seconds` where documented in the OpenAPI
schema.

Avatar creation uses top-level `avatar_handle` plus an `input` union:
`prompt`, `props`, or `photo`. Avatar Video uses top-level `avatar_handle`
plus exactly one of `script` or `video_inputs`. Avatar Video accepts
`quality: "standard" | "plus" | "max"` and defaults to **`plus`**.

Deep guides: [Avatar overview](/models),
[previews](/models/avatar-video-previews), [face swap](/models/face-swap),
[captions](/models/video-captions), [trending](/models/trending-videos).

## Avatar resources, previews, catalog, captions, trending

| Method | Path | Notes |
|---|---|---|
| `GET` | `/v1/avatars` | List avatar resources (compatibility list path). |
| `GET` | `/v1/avatars/:id` | Read one avatar resource. |
| `GET` | `/v1/avatar-videos` | List avatar-video resources. |
| `GET` | `/v1/avatar-videos/:id` | Read one avatar-video resource. |
| `POST` | `/v1/avatar-catalog/search` | Search the avatar catalog. |
| `POST` | `/v1/avatar-video-previews` | Create an avatar-video preview. |
| `GET` | `/v1/avatar-video-previews/:id` | Read a preview. |
| `POST` | `/v1/avatar-video-previews/:id/regenerate` | Regenerate a preview. |
| `POST` | `/v1/avatar-video-previews/:id/generate-video` | Generate a video from a preview. |
| `POST` | `/v1/video-captions` | Submit a video caption job. |
| `GET` | `/v1/video-captions/:id` | Read a video caption resource. |
| `POST` | `/v1/trending-videos/search` | Search TikTok trending video metadata. |

Use [Webhooks](/workflows/webhooks) for terminal event payloads, signature
headers, and retry behavior.

## Actions

Agents Actions have their own run resource and status vocabulary. They are not
jobs and do not appear under `/v1/jobs`. All routes require `actions:read`
except the two writes, which require `actions:write`.

| Method | Path | Notes |
|---|---|---|
| `GET` | `/v1/actions` | List Actions. `limit`, `status`, `trigger_type` filters. |
| `GET` | `/v1/actions/:action_id` | Read one Action. |
| `GET` | `/v1/actions/:action_id/runs` | List runs for an Action. |
| `POST` | `/v1/actions/:action_id/runs` | Start a run via the API-call trigger. Requires `actions:write`. |
| `GET` | `/v1/actions/:action_id/runs/:run_id` | Read one run, aliased under its Action. |
| `GET` | `/v1/action-runs/:run_id` | Read a run receipt. |
| `GET` | `/v1/action-runs/:run_id/status` | Trimmed status payload for polling. |
| `GET` | `/v1/action-runs/:run_id/result` | Terminal receipt. `409 run_not_completed` while still running. |
| `POST` | `/v1/action-runs/:run_id/cancel` | Idempotent cancel. Requires `actions:write`. |

There is no public endpoint to create, edit, or delete an Action, and no
`/v1/action-runs/:run_id/events` endpoint — the `events_url` field on run
receipts is always `null`.
See [Advanced: run a schedule via API](/agents/actions/api-trigger) for the
request body, idempotency rules, and the full error table.

## Formats

Formats have their own run resource, parallel to Actions. All routes require
`formats:read` except the writes (create a run, create a bulk-run queue, cancel),
which require `formats:write`.

| Method | Path | Notes |
|---|---|---|
| `GET` | `/v1/formats` | List Formats visible to the key: your own, plus the first-party catalog. `limit` filter. |
| `GET` | `/v1/formats/:format_id` | Read one Format. The `SKILL.md` body is never returned. |
| `GET` | `/v1/formats/:format_id/runs` | List runs for a Format, newest first. |
| `POST` | `/v1/formats/:format_id/runs` | Start a run via the API-call trigger. Requires `formats:write`. |
| `POST` | `/v1/formats/:format_id/bulk-runs` | Queue up to 100 runs with a `concurrency` window (1–16). Requires `formats:write`. `202` queue receipt. |
| `GET` | `/v1/formats/:handle/:slug` | Read a Format you own by handle and slug. |
| `GET` | `/v1/formats/:handle/:slug/runs` | List runs, addressed by handle and slug. |
| `POST` | `/v1/formats/:handle/:slug/runs` | Start a run, addressed by handle and slug. Requires `formats:write`. |
| `POST` | `/v1/formats/:handle/:slug/bulk-runs` | Same bulk queue, addressed by handle and slug. Requires `formats:write`. |
| `GET` | `/v1/format-run-queues/:queue_id` | Bulk-queue progress (`counts` + per-item status). Requires `formats:read`. |
| `GET` | `/v1/format-runs/:run_id` | Read a run receipt. |
| `GET` | `/v1/format-runs/:run_id/status` | Trimmed status payload for polling. |
| `GET` | `/v1/format-runs/:run_id/result` | Terminal receipt. `409 run_not_completed` while still running. |
| `GET` | `/v1/format-runs/:run_id/events` | Phase timeline for one run, oldest first. |
| `POST` | `/v1/format-runs/:run_id/cancel` | Idempotent cancel. Requires `formats:write`. |
| `POST` | `/v1/format-runs/:run_id/webhook/redeliver` | Re-POST the terminal `format.run.terminal` receipt to the run's webhook URL. Requires `formats:write`. |

Author a Format in the Agents dashboard, or create and edit its package over the
[Contents API](/formats/contents). The curated Formats by Sume are callable
directly at `sume/{slug}` with any valid key; the run is billed to that key. See
[Calling a Format](/formats/call) for the request body and the full
error table, [Bulk runs](/formats/bulk-runs) for the queue contract,
[Runs and results](/formats/runs) for polling and receipts,
[Run webhooks](/agents/run-webhooks) for `format.run.terminal` delivery (not
generation-job [Webhooks](/workflows/webhooks)),
[Structured output](/formats/structured-output) for schema rules,
and the [Format catalog](/formats/catalog) for ready-made Formats.

## Agent Completions

An Agent Completion runs the Agent on an ad-hoc prompt with nothing saved. Reads
require `agent_completions:read`; the two writes require
`agent_completions:write`.

| Method | Path | Notes |
|---|---|---|
| `POST` | `/v1/agent/completions` | Start a completion. Async only — returns `202` and a receipt, not `choices[]`. |
| `GET` | `/v1/agent-runs` | List completions, newest first. |
| `GET` | `/v1/agent-runs/:run_id` | Read a run receipt. |
| `GET` | `/v1/agent-runs/:run_id/status` | Trimmed status payload for polling. |
| `GET` | `/v1/agent-runs/:run_id/result` | Terminal receipt. `409 run_not_completed` while still running. |
| `POST` | `/v1/agent-runs/:run_id/cancel` | Idempotent cancel. |

See [Agent Completions](/agents/completions) for the request shape and how it
differs from an OpenAI chat completion.

## Hidden from public OpenAPI

Some routes are **implemented** on the API but intentionally **omitted** from
the public OpenAPI document (`hidePreLaunchCompatibilityOpenApiPaths`). Do not
treat them as documented public contract until they reappear in
`https://api.sume.com/reference/json`.

| Hidden path family | Status |
|---|---|
| `/v1/assets`, `/v1/assets/upload-url`, `/v1/assets/:id`, `/v1/assets/:id/complete`, `/v1/assets/:id/download-url` | Implemented; hidden from public OpenAPI. Prefer public HTTPS media URLs in generation requests. |
| `/v1/generation/admission-preview` | Implemented; hidden from public OpenAPI. Admission behavior for paid jobs is described in [Generation admission](/workflows/generation-admission). |
| `POST /v1/avatars`, `POST /v1/avatar-videos` | Create via POST on these resource paths is hidden; use canonical / model-run submit endpoints instead. |
| `/health` (unversioned) | Hidden; use `GET /v1/health`. |
| `/v1/models/{model_owner}/{model_name}/{model_version}/runs` | Generic template path hidden; use concrete model paths listed above. |

Related asset-library workflow notes may still describe URL-first inputs even
when upload helpers are not listed in OpenAPI.

## Result and artifact shape

Completed jobs can include public artifacts:

```json
{
  "id": "job_...",
  "status": "completed",
  "result": {
    "artifacts": [
      {
        "id": "artifact_...",
        "url": "https://media.sume.com/artifacts/...",
        "media_type": "image",
        "content_type": "image/png"
      }
    ]
  }
}
```

Public results should use `media.sume.com` URLs. Raw provider URLs and provider
task URLs are not part of the public result contract.

## Error envelope

Errors use a consistent envelope with the request id inside `error`.

```json
{
  "error": {
    "code": "invalid_request",
    "message": "Invalid request body, parameters, or headers.",
    "request_id": "req_..."
  }
}
```

Keep the request id for support and redact API keys, signed URLs, private media
URLs, user ids, workspace ids, and raw provider identifiers from logs.