API reference
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:
Live schema (source of truth for this docs snapshot):
Download it:
Refresh the checked-in snapshot locally:
Authentication
All /v1 API endpoints require a Sume API key except health checks.
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).
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, previews, face swap, captions, trending.
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 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 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. |
As with Actions, there is no public endpoint to create, edit, or delete a Format
— author them in the Agents dashboard. 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 for the request body and the full
error table, Bulk runs for the queue contract,
Runs and results for polling and receipts,
Run webhooks for format.run.terminal delivery (not
generation-job Webhooks),
Structured output for schema rules,
and the Format 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 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. |
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:
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.
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.