TypeScript SDK

A small hand-written transport core (auth, retries, rate-limit, typed errors, pagination) over generated types (schema.d.ts, produced from the API’s OpenAPI). The API is the single source of truth — the SDK never hand-encodes field shapes.

Install

npm install @niravi/sdk

Quickstart

import { connect } from "@niravi/sdk";

const niravi = connect("nv_..."); // dashboard → Settings → Developer

// Semantic search
const hits = await niravi.search("a person walking at sunset", { limit: 5 });
for (const h of hits) console.log(h.video_id, h.timestamp, h.score);

// Drill into one video
const video = await niravi.getVideo(hits[0].video_id);
console.log(await video.transcript());
console.log(await video.recallAsk("what happens in this clip?"));

API

connect(apiKey, opts?) → a Niravi handle.

Method	Description
`niravi.search(query, { limit?, videoId?, searchOptions?, rerank? })`	Semantic search → hits
`niravi.magicSearch(type, query, { limit?, videoId? })`	Typed search (character/location/music/emotion)
`niravi.chat(message, { videoId?, maxTokens? })`	Conversational Q&A
`niravi.videos({ limit?, allPages? })`	List videos (paginated)
`niravi.getVideo(id)`	→ a `Video`
`niravi.upload(filePath, { filename? })`	Upload a video, Node only (write scope)
`niravi.health()` / `niravi.rateLimit`	Health / rate-limit snapshot

Video: transcript(), scenes(), faces(), speakers(), sounds(), screenplay(), recallAsk(question).

Generated types

import type { components } from "@niravi/sdk";
type SearchResponse = components["schemas"]["SearchResponse"];

Auth & options

connect("nv_...", {
  baseUrl: "https://api.niravi.io", // default
  authScheme: "x-api-key",          // default; or "bearer"
  timeoutMs: 30000,
  maxRetries: 3,
});

Errors

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

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