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

curl "https://www.sume.so/api/v1/assets?q=woman%20camera%20hook&source_type=generated&limit=5&sort=relevance" \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI:

sume assets search "woman looking at camera hook" \
  --source-type generated \
  --max-duration 15 \
  --sort relevance \
  --limit 5 \
  --json

Search responses include relevance context when a query is present:

{
  "object": "list",
  "data": [
    {
      "id": "asset_...",
      "object": "asset",
      "title": "Scene 1",
      "media_url": "https://media.sume.so/...",
      "thumbnail_url": "https://media.sume.so/...",
      "start_time_seconds": 0,
      "end_time_seconds": 4.2,
      "metadata": {
        "visual_summary": "Creator faces camera and introduces the product.",
        "cta_present": false
      },
      "search": {
        "mode": "text",
        "score": 0.84,
        "query": "woman looking at camera hook"
      }
    }
  ],
  "has_more": false,
  "next_cursor": null
}

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:

curl https://www.sume.so/api/v1/assets/asset_123 \
  -H "Authorization: Bearer $SUME_API_KEY"

CLI:

sume assets get asset_123 --json
sume assets get asset_123 --download ./assets/

Upload and ingest

For a video that is not already in Sume:

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

Agent usage

Good agent sequence:

sume assets search "close-up product application with strong opening hook" \
  --source-type generated \
  --limit 5 \
  --json

sume assets get <asset_id> --json

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