Python SDK

A small hand-written transport (auth, retries, rate-limit, typed errors, pagination) over generated Pydantic models. The API is the single source of truth — the SDK never hand-encodes field shapes.

Install

pip install niravi

Quickstart

import niravi

client = niravi.connect("nv_...")  # dashboard → Settings → Developer

# Semantic search
for hit in client.search("a person walking at sunset", limit=5):
    print(hit.video_id, hit.timestamp, hit.score)

# Drill into one video
video = client.get_video(hit.video_id)
print(video.transcript())
print(video.recall_ask("what happens in this clip?"))

client.close()

connect() also works as a context manager:

with niravi.connect("nv_...") as client:
    hits = client.search("sunset")

API

Method	Description
`client.search(query, *, limit=None, video_id=None, search_options=None, rerank=None)`	Semantic search → hits
`client.magic_search(type, query, *, limit=None, video_id=None)`	Typed search (character/location/music/emotion)
`client.chat(message, *, video_id=None, max_tokens=None)`	Conversational Q&A
`client.videos(*, limit=50, all_pages=False)`	List videos
`client.get_video(video_id)`	→ a `Video`
`client.upload(file_path, *, filename=None)`	Upload a video (write scope)
`client.health()` / `client.rate_limit`	Health / rate-limit snapshot

Video: detail, transcript(), scenes(), faces(), speakers(), sounds(), music_tracks(), screenplay(), recall_ask(question).

Auth & options

niravi.connect(
    "nv_...",
    base_url="https://api.niravi.io",  # default
    timeout=30.0,
    max_retries=3,
    auth_scheme="x-api-key",           # or "bearer"
)

Errors

Raises typed errors: AuthError (401/403), NotFoundError (404), ValidationError (422), RateLimitError (429), ServerError (5xx) — all subclasses of NiraviError. See Concepts → Errors.

Source: github.com/Niravi-io/niravi-sdk · License Apache-2.0.