Collections
A collection is the top-level container. It fixes two things that every video inside it inherits:
enabled_detectors — the safety-detection allow-list (currently safety_detector). Changing it only affects videos submitted afterward.face_recognition_enabled — the master switch for persons and face entities.
Indexing always embeds with OmniRetriever (3072-dim, multilingual) — our video-embedding model. This is not a parameter you choose; every collection uses it, and it defines the vector space for all search. AI captions, titles, and summaries are generated by OmniCaptioner.
Videos & indexing
A video enters via one of three upload modes (URL, file, resumable) or a live stream. Indexing is asynchronous and runs three phases:
The video moves through processing → ready | failed. Derived content (captions, frames, summary, …) is only guaranteed once the video is ready; asking too early returns 409 video_not_ready with a Retry-After.
The Operation model
Every slow, side-effectful call (ingest, delete, move) returns 202 + an Operation — a uniform async handle.
When polling, only trust done. A non-null error means failure (including partial failure). progress.percent is for display only.
Moments & derived content
A moment is a time-slice view of a video, referenced as {video_id}@{start}-{end} (omit @ for the whole video). Get Moment aggregates whatever you ask for via expand:
caption, transcription, frame, clip, embedding, speakers, entities, events.
Each derived stream also has its own endpoint (e.g. Get Caption, Get Clip) for when you want just one type.
Signed URLs expire
Frames, clips, captions (.vtt), and face images are returned as time-limited signed URLs. Do not cache them past expiry — re-call the endpoint for a fresh link when needed.
