Search

Find moments across every video in your workspace — by meaning, not just keywords.

Semantic search

POST /api/v1/search runs a multimodal embedding search over frames, transcripts, and scene descriptions, fused into one ranked list.

curl https://api.niravi.io/api/v1/search \
  -H "X-API-Key: $NIRAVI_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "two people arguing in a kitchen", "limit": 10}'

Field	Type	Notes
`query`	string	required — natural-language description
`limit`	int	results to return (server default applies if omitted)
`video_id`	string	restrict to a single video
`search_options`	object	advanced tuning (fusion weights, modalities)
`rerank`	bool	apply a second-pass re-ranker

Each hit carries video_id, timestamp, frame_url, and a score.

for hit in client.search("two people arguing in a kitchen", limit=10):
    print(hit.video_id, hit.timestamp, hit.score)

const hits = await niravi.search("two people arguing in a kitchen", { limit: 10 });

Magic search

Typed search narrows to a single dimension — POST /api/v1/search/{type} where type is character, location, music, or emotion.

curl https://api.niravi.io/api/v1/search/emotion \
  -H "X-API-Key: $NIRAVI_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "tense and suspenseful"}'

client.magic_search("character", "a man in a red jacket")
client.magic_search("location", "a rainy city street at night")

await niravi.magicSearch("music", "upbeat synth");
await niravi.magicSearch("emotion", "joyful");

Search a single video instead of the whole corpus by passing video_id (semantic) or scoping a guide’s per-video endpoints — see Videos & processing.