Images & documents

Photos, PDFs, decks and text files go into the same library as your videos, through the same upload, and come back from the same search. A hit on a document names the page and the passage; a hit on a photo or a slide names the region (a box around the object).

How an asset is modelled

Kind	Upload as	How it is indexed
`video`	`.mp4 .mov .mkv .webm .m4v .avi`	Keyframes, transcript, speakers, sounds, OCR, faces
`image`	`.jpg .jpeg .png .webp .heic .heif .tif .tiff .bmp .gif`	One frame: caption, labels, OCR, faces, objects
`document`	`.pdf .docx .pptx .xlsx .odt .odp .rtf .epub .txt .md .html .csv`	One frame per page: the page text (or OCR for a scan), passages with boxes, faces and objects on pictures

Every asset is a “video” in the API (same IDs, same endpoints), with two extra fields on GET /api/v1/videos/{id}: kind (video / image / document) and page_count (documents). A document’s page k sits at timestamp = k − 1, so any endpoint that takes a timestamp works on pages too.

Best results: PDF. Scanned pages are read with OCR: English by default, Hindi too when you add it ("ocr": {"languages": ["en", "hi"]}, see Indexing). Word, PowerPoint, Excel, OpenDocument and RTF files are read as text today: their embedded pictures are not indexed yet, and the legacy binary formats (.doc .ppt .xls) are refused. Export to PDF to keep pictures and layout.

Upload

Images and documents always run on the Arrow engine. The upload is the same call as a video:

curl https://api.niravi.io/api/v1/videos \
  -H "X-API-Key: $NIRAVI_API_KEY" \
  -F "[email protected]"

The response (201) carries kind, so you know how it was read:

{ "success": true, "data": { "video_id": "dd9d63875f73401c", "kind": "document", "status": "processing", ... } }

Poll GET /api/v1/videos/{id} until video.status is completed; index.report then lists what each stage did (pages read, passages, regions, faces).

Read a page

GET /api/v1/videos/{id}/pages/{page} (1-based) returns the page text, its passages in reading order with the box of their lines, the page render and the page’s regions.

curl https://api.niravi.io/api/v1/videos/$DOC/pages/2 -H "X-API-Key: $NIRAVI_API_KEY"

{
  "video_id": "dd9d63875f73401c", "page": 2, "page_count": 17,
  "frame_url": "https://…/f_000002.jpg",
  "text": "NASA LUNAR EXPLORATION …",
  "passages": [ { "idx": 0, "text": "NASA LUNAR EXPLORATION …", "bbox": { "x": 0.016, "y": 0.015, "w": 0.336, "h": 0.051 } } ],
  "regions": { "objects": [ … ], "faces": [ … ], "text": [ … ] }
}

Regions

GET /api/v1/videos/{id}/regions returns every box the index holds for an asset: objects (detected things), faces and text lines. Narrow it with ?page= (documents) or ?timestamp=.

All boxes use one convention: x, y, w, h normalized to 0..1, origin at the top-left of the frame or page, so x * width is a pixel column. Objects carry a label and a confidence; faces carry a person_id once People has grouped them.

Objects come from two detectors: a closed-set one for everyday things (people, vehicles, animals, screens, …) and an open-vocabulary one asked, one phrase at a time, for logo, sign, screen, flag, chart, diagram, map, poster and helmet, plus any phrases you add (see Indexing). On documents, objects are looked for on pages that are mostly picture (scans and figures), not on pages of text.

Search lands on the page and the box

Search with "engine": "arrow" and each hit tells you what it landed on:

Field	On	Meaning
`asset_kind`	every hit	`video`, `image` or `document`
`page`	documents	1-based page of the hit
`passage`	documents	the passage of that page that matches the query best
`region`	images, pages	the box that best matches the query (`x, y, w, h, label, source`)

curl https://api.niravi.io/api/v1/search \
  -H "X-API-Key: $NIRAVI_API_KEY" -H "Content-Type: application/json" \
  -d '{"query": "wind tunnel tests of propellers in descent", "engine": "arrow", "limit": 5}'

{ "video_id": "9e86dca398f14666", "asset_kind": "document", "page": 2,
  "passage": "Vertical or near-vertical descent of VTOL-type, propeller-driven aircraft …", "score": …, … }

Videos, photos and documents rank in one list; filter on asset_kind client-side if you only want one kind.

Delete

DELETE /api/v1/videos/{id} removes an image or a document exactly like a video: it leaves every list at once, and its pages, passages, regions, faces and files are purged in the background. See Videos.