Sume API endpoints list: routes, scopes, idempotency

An index of the Sume API's public routes by family: which need no key, which scope each needs, where Idempotency-Key applies, and the post on each.

6 min readSume
All posts

The Sume API's public routes live under https://api.sume.com/v1. The health, catalog, and background-music routes need no key; every other route takes an API key, and the docs name key scopes for Formats, Actions, Agent Completions, the webhook-secret and test-delivery routes, and job webhook redelivery. The index below groups the routes by family, with the scope each needs, where Idempotency-Key applies, and the post that explains the family.

Routes come from Sume's API reference route map, the Developer API overview, and the live OpenAPI reference, read on 2026-09-27. Downloading the spec and generating a client is covered in the Sume OpenAPI spec; every model id per surface is in every AI model on Sume.

Which routes does the Sume API have?

A dash means the docs give that family no idempotency rule. The live OpenAPI stays the source of truth for fields, so download it when you need the exact schema.

From API reference, Authentication, Webhooks, Generation admission, the model and Format pages, and the OpenAPI reference, read 2026-09-27.
FamilyRoutesKey and scopeIdempotency-Key
Health and catalogGET /v1/health, GET /v1/catalogNo key—
Background musicGET /v1/bgm/catalog, GET /v1/bgm/categories, POST /v1/bgm/pickNo key—
Account and usageGET /v1/me, GET /v1/balance, GET /v1/usageKey—
Webhook secretGET /v1/webhooks/signing-secret, POST /v1/webhooks/signing-secret/rotate, POST /v1/webhooks/test-deliveriesaccount:read; the two POSTs need account:write—
JobsGET /v1/jobs, GET /v1/jobs/{id} plus /status, /result, /events; POST /v1/jobs/{id}/cancelKey—; cancel itself is idempotent on an already-canceled job
Job webhook redeliveryPOST /v1/jobs/{id}/webhook/redeliverjobs:write—
ImagesPOST /v1/images, GET /v1/images/models, GET /v1/images/models/{model_id}/endpointsKeySend one on the create
VideosPOST /v1/videos, GET /v1/videos/{id}, GET /v1/videos/{id}/content, GET /v1/videos/modelsKeySend one on the create; a replay returns the original job
Music RouterPOST /v1/music-router/generate, GET /v1/music-router/modelsKeySend one on the create
Text to speech and speech to textPOST /v1/tts-1.0/generate, POST /v1/tts-router/generate, GET /v1/tts-router/models, POST /v1/stt-1.0/transcribeKeySend one on each create
Background removal and upscalingPOST /v1/rmbg-1.0/remove, POST /v1/image-upscale-1.0/upscale, POST /v1/video-upscale-1.0/upscaleKeySend one on each create
Lip sync and motion controlPOST /v1/veed/fabric-1.0, POST /v1/minimax/h3-max/lip-sync, POST /v1/kling/3.0/motion-controlKeySend one on each create
Avatars and stock avatarsPOST /v1/avatar-1.0/generate, GET /v1/avatar-1.0/avatars and /{id}, POST /v1/avatar-catalog/searchKeySend one on the create
Talking video and previewsPOST /v1/avatar-1.0/talking-video, GET /v1/avatar-videos and /{id}, /v1/avatar-video-previews (create, read, regenerate, generate-video)KeySend one on each create
Face swap (Beta)POST /v1/models/sume/avatar-face-swap/v1.0/runsKeySend one on the create
CaptionsPOST /v1/video-captions, GET /v1/video-captions/{id}KeySend one on the create
Trim, detach, and filterPOST /v1/video-trim, POST /v1/audio-detach, POST /v1/video-filter, POST /v1/video-filter/checkKeyRequired; not on the check
Frames and inspectPOST /v1/video-frames, GET /v1/video-frames/{id}, POST /v1/video-inspect, GET /v1/video-inspect/{id}KeyRequired on inspect; send one on frames
TimelinePOST /v1/timeline-1.0/render, /plan, /audio, /composeKeyRequired; not on /plan
Trending searchPOST /v1/trending-videos/searchKey—
Formats/v1/formats (list, create), /v1/formats/{handle}/{slug} and its /runs and /bulk-runs, /v1/format-runs/{run_id} (read, cancel, redeliver), /v1/format-run-queues/{queue_id}formats:read; creates, cancel, and redeliver need formats:writeOn every run create and bulk queue
Format sharing and files/v1/formats/{handle}/{slug}/grants, /v1/format-grants, /v1/formats/{handle}/{slug}/contentsformats:read; writes need formats:write—
Actions (scheduled runs)/v1/actions and /v1/actions/{action_id} (read), /v1/actions/{action_id}/runs (list, create), /v1/action-runs/{run_id} (read, cancel)actions:read; run create and cancel need actions:writeOn every run request, 1–255 characters
Agent CompletionsPOST /v1/agent/completions, GET /v1/agent-runs, /v1/agent-runs/{run_id} (read, cancel)agent_completions:read; the two writes need agent_completions:writeA replay returns the original receipt
curl https://api.sume.com/reference/json \
  -o sume-openapi.json

Which scope does my key need?

Families marked Key need a valid API key, and the docs name no scope for them. The scoped families follow these rules:

  • Scopes are fixed when a key is created and cannot be added later. A key made before the Actions or Formats scopes existed gets 403 insufficient_scope on those routes (on a Format, never 404); create a new key and rotate to it.
  • The webhook-secret routes read with account:read, and rotation and test deliveries need account:write; redelivering a real job webhook needs jobs:write.
  • Hosted MCP under OAuth uses its own scopes: mcp:read for read-only tools and mcp:write for mutating and paid ones.

Which routes are legacy or retiring?

These still answer but are not where new work should go. Moving from Video 1.0 and Image 1.0 covers the switch.

  • Image 1.0 (POST /v1/image-1.0/generate) and Video 1.0 (POST /v1/video-1.0/generate) are retiring soon. Use POST /v1/images and POST /v1/videos.
  • Music 1.0 (POST /v1/music-1.0/generate) is retiring gradually and resolves through the Music Router.
  • The Image Router routes are deprecated in favor of /v1/images, and the legacy Video Router routes point new integrations to /v1/videos. Both still work.
  • Model-run aliases under /v1/models/…/runs stay in the public OpenAPI and keep working. Prefer the canonical path when both exist.
  • POST /v1/avatar-1.0/image-to-video is a deprecated alias of POST /v1/veed/fabric-1.0.

What does this list leave out?

Some routes are implemented but omitted from the public OpenAPI on purpose, among them the /v1/assets family, /v1/generation/admission-preview, and POST creates on /v1/avatars and /v1/avatar-videos. The docs say not to treat them as public contract until they appear in the live OpenAPI.

The OpenAPI document also carries routes this index skips, experimental and development-first ones among them. Their docs pages mark those, so read a route's page before you build on it.

Sources

Related posts

More in Developers

All Developers posts

Written by Sume