> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixpeek.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Extract Features

> Turn raw files into searchable documents by picking what you want to search by per file type — collections run the pipeline for you

## Collections

Collections bind a bucket to a processing pipeline. You choose **[features](/docs/processing/features)** — what you want to search by (visual similarity, faces, on-screen text, ...) — and Mixpeek resolves the pipeline internally. When you submit a batch, the engine processes each object and produces searchable documents.

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/collections" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "product-images",
    "source": { "type": "bucket", "bucket_ids": ["'$BUCKET_ID'"] },
    "features": ["image_search"]
  }'
```

Discover the menu with `GET /v1/collections/features` — every modality's unit, base feature, and add-ons (faces, on-screen text, layout, ...), with live rates. Add-on features like `faces` create a companion collection over the same source, so each pipeline's outputs stay independently versioned and queryable.

A single object can feed multiple collections — each extracting different features. Documents retain lineage to the source object via `root_object_id`.

[Features guide →](/docs/processing/features) · [Collection API →](/docs/api-reference/collections/create-collection)

<Note>
  Existing configs using explicit `feature_extractor` objects keep working as a deprecated alias — see the [migration guide](/docs/processing/extractor-migration). For advanced wiring (custom input mappings, field passthrough, parameters), see [Pipeline Configuration](/docs/processing/feature-extractors).
</Note>

### Know the cost before you run

`POST /v1/organizations/billing/estimate` quotes planned ingestion in dollars — same rating engine that bills you:

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/organizations/billing/estimate" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [{ "mime_type": "video/mp4", "minutes": 42 }],
    "features": ["faces", "onscreen_text"]
  }'
```

See [Billing & Pricing](/docs/platform/billing) for units, rates, and tier usage pools.

### Embedding task

Instruction-aware embedding models use a **task hint** to optimize the embedding for a specific downstream use case. Set `embedding_task` at the collection level so it applies to every task-aware model in the pipeline.

```bash theme={null}
curl -X POST "https://api.mixpeek.com/v1/collections" \
  -H "Authorization: Bearer $MIXPEEK_API_KEY" \
  -H "X-Namespace: $NAMESPACE_ID" \
  -H "Content-Type: application/json" \
  -d '{
    "collection_name": "product-clusters",
    "embedding_task": "clustering",
    "source": { "type": "bucket", "bucket_ids": ["'$BUCKET_ID'"] },
    "features": ["text_search"]
  }'
```

| Task                  | Use Case                                     | Default |
| --------------------- | -------------------------------------------- | ------- |
| `retrieval_document`  | Search: find documents from queries          | **Yes** |
| `retrieval_query`     | Rare at index time — query-side is automatic | No      |
| `semantic_similarity` | Symmetric comparison (dedup, matching)       | No      |
| `classification`      | Document categorization pipelines            | No      |
| `clustering`          | Grouping documents into clusters             | No      |

<Info>
  You almost never need to set this. The default `retrieval_document` is correct for search, and at query time Mixpeek automatically uses `retrieval_query`. Only override for clustering, classification, or symmetric similarity. Non-instruction-aware models ignore this setting.
</Info>

## Feature URIs

Every extracted feature is addressed by a URI that pins it to a specific pipeline version:

```
mixpeek://{pipeline_name}@{version}/{output_name}
```

Feature URIs are referenced by retriever stages, taxonomies, and clustering jobs. They guarantee query-time compatibility with the extraction pipeline — swap the URI, re-embed, everything downstream stays consistent. Discover the URIs a collection produces with `GET /v1/collections/{id}/features` rather than constructing them by hand; see [Pipeline Configuration](/docs/processing/feature-extractors#feature-uris-the-stable-contract).

## Tiered pipelines

When a batch is submitted, the engine runs a DAG of pipelines:

1. **Tier 1** collections process raw objects from the bucket
2. **Tier 2** collections consume Tier 1 documents as input
3. Each tier waits for dependencies before executing

```
video → scenes (Tier 1) → faces per scene (Tier 2) → expressions per face (Tier 3)
```

Collections define the pipeline through their `source` and feature configuration. Dependencies are resolved automatically. See [Multi-Tier Feature Extraction](/docs/processing/multi-tier-extractors).

## What Mixpeek extracts

| Modality | Unit             | Base feature                                       | Add-on features                                                           |
| -------- | ---------------- | -------------------------------------------------- | ------------------------------------------------------------------------- |
| Image    | per image        | `image_search` — visual embeddings                 | `faces`, `multimodal_understanding`                                       |
| Video    | per minute       | `video_search` — scene embeddings                  | `faces`, `onscreen_text`, `audio_fingerprint`, `multimodal_understanding` |
| Audio    | per minute       | `audio_search` — acoustic fingerprint + embeddings | `multimodal_understanding`                                                |
| Document | per page         | `document_search` — page embeddings                | `faces`, `document_layout`, `multimodal_understanding`                    |
| Text     | per token        | `text_search` — semantic embeddings                | `multimodal_understanding`                                                |
| Web      | per crawled page | `web_crawl` — crawl + extract                      | —                                                                         |

Clustering and taxonomy enrichment are included on every modality at no additional charge. The live menu (with rates) is always `GET /v1/collections/features` — see the [Features guide](/docs/processing/features).

## Custom extractors

For extraction logic beyond the built-in features, build custom extractors:

```bash theme={null}
pip install mixpeek
mixpeek plugin init my-extractor     # Scaffold from template
mixpeek plugin test my-extractor     # Validate locally
mixpeek plugin publish my-extractor  # Upload and deploy
```

Custom extractors run on managed infrastructure with access to GPU/CPU resources, HuggingFace models, and LLM services. Once published, select yours in any collection as `features: ["custom:my-extractor"]` — it prices per unit from its declared compute profile, exactly like native features.

See the [full custom extractors guide](/docs/processing/custom-extractors) for manifest format, pipeline hooks, security constraints, and deployment lifecycle.

[Custom Extractors →](/docs/processing/custom-extractors)