Skip to main content

​
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. You never have to pick it: embedding_model is optional on Create Collection and defaults to omni_retriever, currently the only accepted value. 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.
Two consumption patterns — poll Get Operation, or register a webhook.

​
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.