Semantic Search

Endpoints

POST /video/{video_id}/semantic-search/
POST /collection/{collection_id}/semantic-search/

Use semantic search when you know which semantic index or indexes to search directly.

Request body

Field	Type	Required	Description
`query`	string	yes	Text to search for.
`index_names`	string/list	no	Semantic index names to search.
`index_ids`	string/list	no	Semantic index IDs to search.
`top_k`	integer	no	Maximum returned moments. Defaults to `10`.
`score_threshold`	number	no	Minimum similarity score.
`filter`	list/object	no	Structured filter over supported fields/vector metadata.
`return_fields`	string/list/dict	no	Select indexes to hydrate under `shot.metadata["indexes"]`.

If index_names and index_ids are omitted, VideoDB searches all semantic indexes in scope.

The Python SDK argument is index_names, not singular index_name. Use index_ids for ID selection.

Example

results = video.semantic_search(
    query="happy reunion outside a shop",
    index_names=["scene"],
    top_k=10,
    score_threshold=0.7,
    return_fields=["scene"],
)

for shot in results:
    print(shot.start, shot.end, shot.search_score)

Example with index IDs

results = collection.semantic_search(
    query="person presenting at a podium",
    index_ids=["idx_scene_123"],
    top_k=20,
)

Response

Returns a SearchResult containing Shot objects. SearchResult.compile() can compile all returned shots into one stream.

Overview

Authentication

Collections

Videos

Streaming & Playback

Transcription

Search V2 & Ask

Indexing & Search

Scene & Frame Analysis

Advanced Operations

Audio

Images

AI Generation

Timeline & Compilation

Billing

Downloads

Utilities

Assets

Editor

Transcode

Meeting

Capture

RTStream

RTStream Transcription

RTStream Scene Indexing

RTStream Events & Alerts

Endpoints

Request body

Example

Example with index IDs

Response

​Endpoints

​Request body

​Example

​Example with index IDs

​Response

Endpoints

Request body

Example

Example with index IDs

Response