Jobs and assets

Most Sume create operations return before processing is complete. Store the returned job id, poll status, then fetch the result.

List and inspect jobs

Supported public job types:

Fetch results

--download downloads safe public media URLs returned by Sume into a local directory. It does not make provider calls. Do not paste full media URLs or private identifiers into reports.

Inline wait

For short jobs, create and wait in one command:

For longer jobs, avoid holding an agent turn open indefinitely:

Asset Library search

Asset Library stores searchable scene-level assets scoped to the API-key workspace.

Search first, then fetch one scene:

Preserve search context with --query and --search-mode. Include --search-score <score> only when the search result score is non-null; do not send 0 as a placeholder.

Asset search filters

Option	Use
--limit <n> / --cursor <cursor>	Page through results.
--search-mode <auto|text>	Choose search mode. assets search defaults to text.
--source-type <type>	Filter by source video type, such as generated or upload.
--segment-type <type>	Filter by indexed scene segment type.
--brand <brand> / --product <product>	Filter by indexed brand/product mentions.
--tag <tag> / --keyword <keyword>	Filter by tags or keywords.
--cta-present <bool>	Filter by CTA presence.
--min-duration <seconds> / --max-duration <seconds>	Filter by scene duration.
--created-after <iso> / --created-before <iso>	Filter by creation time.
--sort <sort>	relevance, created_at_desc, created_at_asc, or duration_desc.

Scene media fields

Asset responses can distinguish scene media from source media:

• clip_url is a scene-specific playable clip when materialized.
• source_media_url is the original source video.
• scene timestamps identify where the scene appears in the source.

Prefer clip_url when present. If a scene clip is missing, only use the source video plus timestamps in workflows that can trim safely.

Upload a video to Asset Library

Create a temporary upload target:

The response includes:

• upload_url: temporary signed storage URL; treat as sensitive.
• required_headers: headers to send to storage.
• object_key: storage object key for finalize.
• media_url: Sume media URL when available.

Upload file bytes to upload_url with only required_headers. Do not send the Sume API Authorization header to the storage URL.

Then finalize:

Finalizing starts Asset Library processing. Search or list assets after ingest completes.

Face Swap upload purpose

Face Swap source videos use a different upload purpose:

Use the resulting Sume media URL with sume face-swap create.