> ## Documentation Index
> Fetch the complete documentation index at: https://api-tools.memories.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Core Concepts

> Collections, videos, the async Operation model, moments, and derived content — the mental model behind every endpoint.

## 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](/datalake/videos/upload-video-url), [file](/datalake/videos/upload-video-file), [resumable](/datalake/videos/upload-video-resumable)) or a [live stream](/datalake/streams/open-stream). Indexing is asynchronous and runs three phases:

```
preprocess → index → derive
```

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.

<Warning>
  When polling, **only trust `done`**. A non-null `error` means failure (including partial failure). `progress.percent` is for display only.
</Warning>

```json theme={null}
{ "operation": "op_xxx", "kind": "ingest", "done": false, "cancelled": false,
  "resource": "vid_xxx",
  "progress": { "preprocess": "done", "index": "running", "derive": "pending", "percent": 45 },
  "error": null }
```

Two consumption patterns — **poll** [Get Operation](/datalake/operations/get-operation), or register a [webhook](/datalake/reference/webhooks).

## 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](/datalake/moments/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](/datalake/moments/get-caption), [Get Clip](/datalake/moments/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.

| Asset                           | TTL    |
| ------------------------------- | ------ |
| Clip cached link                | 5h     |
| Video `source_url` / face image | 24h    |
| Search thumbnail                | 15 min |
| `search/images` upload          | 1h     |