Asset Library

Asset Library exposes scene-level assets indexed from uploaded videos, generated videos, and source media. Search returns records scoped to the API-key workspace.

Mental model

Object	What it means
Source video	The original uploaded or generated video that was ingested.
Scene asset	A searchable clip/segment from that video with timing and metadata.
Metadata	Transcript, visual summary, action labels, brand/product mentions, tags, keywords, CTA presence, and timing when available.
Safe URL	A stable media or thumbnail URL that can be reused by tools. Avoid logging full query-string URLs.

Assets without scene metadata are not returned by search until indexing creates scene rows.

Search scenes

CLI:

Search responses include relevance context when a query is present:

Treat the shape above as illustrative. The API reference is the source of truth for exact fields.

Filters

Query parameter	CLI flag	Use for
q	assets search "<query>" or assets list --query	Natural-language or keyword scene search.
search_mode	--search-mode auto|text	Text/metadata search mode.
source_type	--source-type	Uploaded vs generated/source categories.
segment_type	--segment-type	Hook, product demo, CTA, or other indexed scene roles.
brand	--brand	Brand mentions.
product	--product	Product mentions.
tag	--tag	Reusable asset tags.
keyword	--keyword	Indexed keywords.
cta_present	--cta-present true|false	Scenes with or without calls to action.
min_duration_seconds / max_duration_seconds	--min-duration / --max-duration	Clip length constraints.
created_after / created_before	--created-after / --created-before	Time windows.
sort	--sort	relevance, created_at_desc, created_at_asc, or duration_desc.

Fetch one asset

Search first, then fetch one scene when you need fuller metadata:

CLI:

Upload and ingest

For a video that is not already in Sume:

1. Call POST /uploads/presign with file name, content type, and size.
2. Upload bytes to the returned signed URL using required_headers.
3. Call POST /assets with the returned object_key.
4. Watch the returned job or ingest status.
5. Search /assets once scene indexing is complete.

Agent usage

Good agent sequence:

For agents, keep search rows alongside fetched details because the search row carries search.mode, search.score, and the query that matched it.