API reference
This page is a human-readable route map for the Sume Developer API. This page is not a second schema. For exact JSON request/response shapes, enums, and field requirements, use the live OpenAPI document. The Markdown tables on this page can be older than the live document.
OpenAPI schema
Local docs snapshot:
Live schema (source of truth for this docs snapshot):
Download the schema:
Refresh the checked-in snapshot locally:
Authentication
You must send a Sume API key to all /v1 API endpoints, except these public
routes:
GET /v1/health, GET /v1/catalog, GET /v1/openapi.json,
GET /v1/bgm/catalog, GET /v1/bgm/categories, and POST /v1/bgm/pick.
The API also accepts x-api-key: $SUME_API_KEY. API responses do not 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 | The available balance in USD. |
GET | /v1/usage | Usage ledger entries such as reservations, captures, refunds, and top-ups. |
Jobs
| Method | Path | Notes |
|---|---|---|
GET | /v1/jobs | List workspace jobs. You can filter 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. It includes public artifact URLs when they are available. |
POST | /v1/jobs/:id/cancel | Cancel a job before generation starts. After generation starts, the endpoint returns 409 job_generation_already_started. Idempotent on an already-canceled job. |
GET | /v1/jobs/:id/events | Public timeline events. Use them to debug and to recover jobs. |
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 that the live OpenAPI schema documents (for example Avatar photo
input.image_url, Avatar Video product_image / scene.image_url).
The API rejects localhost, private-network, non-HTTPS, and non-image responses before it submits the generation. First-party upload helpers are not the default public API path for normal integrations (refer to Hidden from public OpenAPI).
Canonical generation paths
For new integrations, these product-style endpoints are the best choice.
| 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 stay in the public OpenAPI and continue
to work. When both exist, the canonical paths above are the better choice.
| 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. |
Where the OpenAPI schema documents them, submit endpoints support the common
communication fields mode, webhook_url, and wait_timeout_seconds.
Avatar creation uses a top-level avatar_handle and an input union:
prompt, props, or photo. Avatar Video uses a top-level avatar_handle
and exactly one of script or video_inputs. Avatar Video accepts
quality: "standard" | "plus" | "max". The default is 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. |
For terminal event payloads, signature headers, and retry behavior, refer to Webhooks.
Actions
Agents Actions have their own run resource and status vocabulary. Actions are
not jobs, and they do not show in /v1/jobs. The key must have actions:read
for all routes, except the two writes. For the two writes, the key must have
actions:write.
| Method | Path | Notes |
|---|---|---|
GET | /v1/actions | List Actions. Filters: limit, status, trigger_type. |
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 through the API-call trigger. actions:write is necessary. |
GET | /v1/actions/:action_id/runs/:run_id | Read one run. This path is an alias 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. Returns 409 run_not_completed while the run is in progress. |
POST | /v1/action-runs/:run_id/cancel | Idempotent cancel. actions:write is necessary. |
There is no public endpoint to create, edit, or delete an Action. There is
also no /v1/action-runs/:run_id/events endpoint. The events_url field on
run receipts is always null.
For the request body, idempotency rules, and the full error table, refer to
Advanced: run a schedule via API.
Formats
Formats have their own run resource, parallel to Actions. The key must have
formats:read for all routes, except the writes (create a run, create a bulk-run queue, cancel).
For the writes, the key must have formats:write.
| Method | Path | Notes |
|---|---|---|
GET | /v1/formats | List the Formats that the key can see: your own Formats and the first-party catalog. limit filter. |
GET | /v1/formats/:format_id | Read one Format. The endpoint does not return the SKILL.md body. |
GET | /v1/formats/:format_id/runs | List runs for a Format, newest first. |
POST | /v1/formats/:format_id/runs | Start a run through the API-call trigger. formats:write is necessary. |
POST | /v1/formats/:format_id/bulk-runs | Queue a maximum of 100 runs with a concurrency window (1–16). formats:write is necessary. 202 queue receipt. |
GET | /v1/formats/:handle/:slug | Read a Format that 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. formats:write is necessary. |
POST | /v1/formats/:handle/:slug/bulk-runs | Same bulk queue, addressed by handle and slug. formats:write is necessary. |
GET | /v1/format-run-queues/:queue_id | Bulk-queue progress (counts + per-item status). formats:read is necessary. |
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. Returns 409 run_not_completed while the run is in progress. |
GET | /v1/format-runs/:run_id/events | Phase timeline for one run, oldest first. |
POST | /v1/format-runs/:run_id/cancel | Idempotent cancel. formats:write is necessary. |
POST | /v1/format-runs/:run_id/webhook/redeliver | Re-POST the terminal format.run.terminal receipt to the webhook URL of the run. formats:write is necessary. |
To author a Format, use the Agents dashboard. You can also use the
Contents API to create and edit the package of a Format.
Any valid key can call the curated Formats by Sume directly at sume/{slug}.
Sume bills the run to that key.
For the request body and the full error table, refer to
Calling a Format. For the queue contract, refer to
Bulk runs. For polling and receipts, refer to
Runs and results. For format.run.terminal delivery, refer to
Run webhooks (not generation-job
Webhooks). For schema rules, refer to
Structured output. For ready-made Formats, refer
to the Format catalog.
Agent Completions
An Agent Completion runs the Agent on an ad-hoc prompt with nothing saved. For
reads, the key must have agent_completions:read. For the two writes, the key
must have 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. Returns 409 run_not_completed while the run is in progress. |
POST | /v1/agent-runs/:run_id/cancel | Idempotent cancel. |
For the request shape and the differences from an OpenAI chat completion, refer to Agent Completions.
Hidden from public OpenAPI
The API implements some routes, but intentionally does not include them
in the public OpenAPI document (hidePreLaunchCompatibilityOpenApiPaths). Do
not use these routes as a documented public contract until they are in
https://api.sume.com/reference/json again.
| 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. In generation requests, it is better to use public HTTPS media URLs. |
/v1/generation/admission-preview | Implemented. Hidden from public OpenAPI. Generation admission describes the admission behavior for paid jobs. |
POST /v1/avatars, POST /v1/avatar-videos | Create through POST on these resource paths is hidden. Use the canonical / model-run submit endpoints. |
/health (unversioned) | Hidden. Use GET /v1/health. |
/v1/models/{model_owner}/{model_name}/{model_version}/runs | The generic template path is hidden. Use the concrete model paths that the tables above list. |
Related asset-library workflow notes can still describe URL-first inputs when OpenAPI does not list the upload helpers.
Result and artifact shape
Completed jobs can include public artifacts:
Public results must 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. The request id is inside error.
Keep the request id for support. Redact API keys, signed URLs, private media URLs, user ids, workspace ids, and raw provider identifiers from logs.