API reference

This page is a route-level reference for the Sume Public API. It is designed to be readable in the docs shell while keeping the OpenAPI schema as the exact source of truth.

OpenAPI schema

Preview schema:

Production schema:

Download it:

Authentication

All Public API v1 endpoints use workspace-scoped API keys.

The legacy X-Api-Key header is accepted for existing keys, but Authorization: Bearer is preferred. Sume resolves workspace and owner scope from the key, so request bodies should not include workspace_id or user_id.

Account and credits

Method	Path	Returns	Notes
GET	/me	account	Authenticated user, workspace, and API key metadata.
GET	/credits	credits	Plan, monthly and bonus credits, remaining credits, and active generation capacity.

Brand DNA

Method	Path	Returns	Notes
GET	/brand	brand list	Lists sanitized Brand DNA profiles visible to the workspace.
GET	/brand/current	brand	Returns the current server-selected workspace Brand DNA profile.

Brand responses can include images[].reference_url values. Use those URLs as reference_image_urls for image generation when present.

Avatars

Method	Path	Returns	Notes
GET	/avatars	avatar list	Public and workspace avatars usable by the key.
GET	/avatars/{avatarId}	avatar	One avatar with media and capability metadata.

Avatar capabilities indicate whether the avatar can be used for talking-head video, UGC ad video, or Face Swap workflows.

Jobs

Method	Path	Returns	Notes
GET	/jobs	job list	Supports limit, cursor, type, and status.
GET	/jobs/{jobId}	job	Current status and sanitized error/result URL fields.
GET	/jobs/{jobId}/result	job with result	Final output payload for completed jobs when available.

Job objects expose public status and output fields only. Internal provider payloads are not part of the public contract.

Image generation

Method	Path	Returns	Credits
POST	/images/generations	image_generation	May reserve or spend credits.

Common request fields include:

Field	Type	Notes
prompt	string	Main image instruction.
aspect_ratio	string	Output aspect ratio.
resolution	string	Output size preference when supported.
quality	string	Quality preference when supported.
image_count or n	integer	Minimum 1; current CLI guidance recommends one reliable output per job.
reference_image_urls	string array	HTTPS image references, including Brand reference_url values when available.

Video generation

Method	Path	Returns	Credits
POST	/videos/generations	video_generation	May reserve or spend credits.

Common request fields include:

Field	Type	Notes
prompt	string	Main video instruction.
aspect_ratio	string	For example 9:16.
duration	number	Requested duration in seconds.
generate_audio	boolean	Whether to request audio when supported.
resolution	string	Output resolution preference.

AI Ads video

Method	Path	Returns	Credits
POST	/ads/videos	ad_video_generation	Reserves credits before accepting the job.

Required field:

Field	Type	Notes
script	string	Required, 3 to 1800 characters.

Selected optional fields:

Field	Type	Notes
ad_format	enum	talking_heads, ugc_ads, or video; defaults to talking_heads.
avatar_id or avatar_slug	string	Required for avatar-based ad formats.
locale	enum	en or ko.
duration_seconds	number	Sume may clamp to supported durations by ad format.
reference_image_urls	string array	Up to 9 HTTPS image references.
reference_video_urls	string array	Only supported for ad_format: "video".

Face Swap

Method	Path	Returns	Credits
POST	/face-swap	face_swap	Reserves credits per avatar/job.

Face Swap requires a Sume media URL created with upload purpose face_swap_source_video.

Field	Type	Notes
source_video_url	URI	Sume media URL returned by the upload flow.
avatar_ids	string array	1 to 5 avatar ids.
duration_seconds	number	Maximum 15 seconds.
trim_start_seconds	number	Optional trim start.
trim_end_seconds	number or null	Optional trim end.
aspect_ratio	enum	16:9, 9:16, 1:1, 4:3, 3:4, or 21:9.

Reference Analysis

Method	Path	Returns	Credits
POST	/reference-analysis	reference_analysis	Requires credits and creates an async analysis job.

Supported input is a public TikTok or Instagram Reel URL. Poll the returned job id, then fetch the result from /jobs/{jobId}/result.

Uploads and Asset Library

Method	Path	Returns	Notes
POST	/uploads/presign	upload	Creates a temporary signed upload URL.
POST	/assets	asset_upload	Finalizes an uploaded video and starts Asset Library processing.
GET	/assets	asset list	Lists or searches indexed scene assets.
GET	/assets/{assetId}	asset	Reads one scene asset.

Upload purposes:

Purpose	Use for
asset_library_video	Videos that should be ingested into Asset Library scene search.
face_swap_source_video	Source videos used by Face Swap.

The upload response includes a temporary upload_url, an object_key, media_url, and required_headers. Treat them as sensitive operational values. Do not send the Sume API Authorization header to the storage upload URL.

Finalize Asset Library upload:

Search indexed scenes:

Asset results include a scene-level media_url when available, optional thumbnail/source video fields, source type, search score, and scene metadata.

List response

List endpoints use this envelope:

Use limit to control page size and cursor to continue from next_cursor.

Error response

Common status codes include:

Status	Meaning
400	Invalid request body, unsupported input, or validation error.
401	Missing or invalid API key.
402	Insufficient credits.
403	API key lacks access to the requested resource or action.
404	Resource not found in the current workspace scope.
409	Conflict, duplicate, or incompatible state.
413	Uploaded/requested media is too large.
429	Rate limit or active generation limit.
500, 502, 503	Internal, upstream, or provider availability failure.

When reporting an issue to Sume, include request_id and the sanitized endpoint or job id. Do not include API keys, signed URLs, object keys, private media URLs, full provider payloads, user emails, or workspace/user ids.