Skip to main content

​
Collections

Collections bind a bucket to a processing pipeline. You choose 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. 
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 → · Collection API →
Existing configs using explicit feature_extractor objects keep working as a deprecated alias — see the migration guide. For advanced wiring (custom input mappings, field passthrough, parameters), see Pipeline Configuration.

​
Know the cost before you run

POST /v1/organizations/billing/estimate quotes planned ingestion in dollars — same rating engine that bills you: 
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 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. 
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"]
  }'
TaskUse CaseDefault
retrieval_documentSearch: find documents from queriesYes
retrieval_queryRare at index time — query-side is automaticNo
semantic_similaritySymmetric comparison (dedup, matching)No
classificationDocument categorization pipelinesNo
clusteringGrouping documents into clustersNo
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.

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

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

​
What Mixpeek extracts

ModalityUnitBase featureAdd-on features
Imageper imageimage_search — visual embeddingsfaces, multimodal_understanding
Videoper minutevideo_search — scene embeddingsfaces, onscreen_text, audio_fingerprint, multimodal_understanding
Audioper minuteaudio_search — acoustic fingerprint + embeddingsmultimodal_understanding
Documentper pagedocument_search — page embeddingsfaces, document_layout, multimodal_understanding
Textper tokentext_search — semantic embeddingsmultimodal_understanding
Webper crawled pageweb_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.

​
Custom extractors

For extraction logic beyond the built-in features, build custom extractors: 
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 for manifest format, pipeline hooks, security constraints, and deployment lifecycle. Custom Extractors →