Overview

The Sume Public API is a thin programmatic surface over workspace-scoped Sume app capabilities. It is designed for server integrations, CLI automation, MCP wrappers, and agent tools.

Endpoint groups

Group	Endpoints	Use for
Account	GET /me, GET /credits	Verify auth, workspace scope, plan, credits, and active generation capacity.
Brand	GET /brand, GET /brand/current	Read sanitized Brand DNA profiles available to the workspace.
Avatars	GET /avatars, GET /avatars/{avatarId}	Pick public or workspace-owned avatars for ads and Face Swap workflows.
Jobs	GET /jobs, GET /jobs/{jobId}, GET /jobs/{jobId}/result	List jobs, poll status, and retrieve generated or analyzed outputs.
Generation	POST /images/generations, POST /videos/generations, POST /ads/videos, POST /face-swap, POST /reference-analysis	Create asynchronous media or analysis jobs. These endpoints may spend credits.
Uploads	POST /uploads/presign, POST /assets	Upload videos and finalize them for Asset Library ingest or feature-specific workflows.
Asset Library	GET /assets, GET /assets/{assetId}	Search indexed scene assets and retrieve reusable clip/source metadata.

Async workflow

Most write endpoints create a job:

1. Check account and credits with /me and /credits.
2. Create a job, such as POST /videos/generations.
3. Poll GET /jobs/{jobId} until the job reaches a terminal state.
4. Fetch GET /jobs/{jobId}/result.
5. Use returned public media URLs or metadata in the next workflow step.

curl https://www.sume.so/api/v1/videos/generations \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A creator demonstrates a vitamin serum in a bright studio.",
    "aspect_ratio": "9:16",
    "duration": 5,
    "generate_audio": false
  }'

Upload workflow

Use uploads when an endpoint needs user-provided media.

curl https://www.sume.so/api/v1/uploads/presign \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "reference.mp4",
    "content_type": "video/mp4",
    "size_bytes": 12000000
  }'

Then upload bytes to the returned upload_url with the returned required_headers. For Asset Library ingest, finalize with:

curl https://www.sume.so/api/v1/assets \
  -H "Authorization: Bearer $SUME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "object_key": "uploads/...",
    "file_name": "reference.mp4"
  }'

For Face Swap, create the upload URL with the documented purpose, upload the source video, then pass the returned media URL to POST /face-swap.

Pagination

List endpoints use cursor pagination:

{
  "object": "list",
  "data": [],
  "has_more": false,
  "next_cursor": null
}

Pass next_cursor back as cursor to continue.

Error envelope

{
  "error": {
    "code": "invalid_request",
    "message": "A human-readable error message.",
    "details": {}
  },
  "request_id": "req_..."
}

Common statuses include 400, 401, 402, 403, 404, 409, 413, 429, 500, 502, and 503, depending on endpoint and feature state.

Source of truth

This preview embeds the current public OpenAPI schema at /api/openapi.json. Production Sume serves the live schema from /api/v1/openapi.json.