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

# Reverse Media Search

> Find visually similar content using images or videos as your search query

> [card] [Search your own images and video](https://studio.mixpeek.com/namespaces/create?mode=managed\&utm_source=docs\&utm_medium=docs_reverse_search\&utm_campaign=managed_onramp)
>
> Create a namespace, upload a few assets, and run a visual similarity search in minutes — no API key setup required.

> [!TIP]
>
> Reverse media search uses the warehouse's Decompose layer to extract visual features, then queries them in the Reassemble layer. See [Multi-Stage Retrieval](https://docs.mixpeek.com/docs/retrieval/multi-stage-deep-dive.md) for composing pipelines.

## Input Methods

| Method | Example | Speed |
| - | - | - |
| Pre-computed embedding | `{"embedding": [0.1, 0.2, ...]}` | Fastest |
| Image URL | `{"url": "https://example.com/img.jpg"}` | Fast |
| Video URL | `{"url": "s3://bucket/video.mp4"}` | Medium |
| Base64 | `{"base64": "data:image/jpeg;base64,..."}` | Fast |

## 1. Create a Bucket

```bash theme={null}
POST /v1/buckets
{
  "bucket_name": "visual-assets",
  "bucket_schema": {
    "properties": {
      "asset_url": { "type": "image", "required": true },
      "brand": { "type": "text" },
      "campaign_id": { "type": "text" }
    }
  }
}
```

## 2. Create a Collection

**For images:**

```bash theme={null}
POST /v1/collections
{
  "collection_name": "product-images",
  "source": { "type": "bucket", "bucket_ids": ["bkt_visual_assets"] },
  "feature_extractor": {
    "feature_extractor_name": "image_extractor",
    "version": "v1",
    "input_mappings": { "image_url": "asset_url" },
    "parameters": { "model": "clip-vit-large-patch14" },
    "field_passthrough": [
      { "source_path": "brand" },
      { "source_path": "campaign_id" }
    ]
  }
}
```

**For videos:**

```bash theme={null}
POST /v1/collections
{
  "collection_name": "video-segments",
  "source": { "type": "bucket", "bucket_ids": ["bkt_visual_assets"] },
  "feature_extractor": {
    "feature_extractor_name": "multimodal_extractor",
    "version": "v1",
    "input_mappings": { "video": "asset_url" },
    "parameters": {
      "scene_detection_threshold": 0.3,
      "extract_keyframes": true
    }
  }
}
```

## 3. Ingest Assets

```bash theme={null}
POST /v1/buckets/{bucket_id}/objects
{
  "key_prefix": "/products/shoes",
  "blobs": [
    { "property": "asset_url", "type": "image", "data": "s3://my-bucket/products/sneaker-001.jpg" }
  ],
  "brand": "Nike",
  "campaign_id": "fall-2025"
}
```

## 4. Process

```bash theme={null}
POST /v1/buckets/{bucket_id}/batches
{ "object_ids": ["obj_001", "obj_002"] }

POST /v1/buckets/{bucket_id}/batches/{batch_id}/submit
```

## 5. Create a Retriever

```bash theme={null}
POST /v1/retrievers
{
  "retriever_name": "reverse-image-search",
  "collection_identifiers": ["col_product_images"],
  "input_schema": {
    "query_image": { "type": "image", "required": true },
    "min_similarity": { "type": "number", "default": 0.7 }
  },
  "stages": [
    {
      "stage_name": "visual_search",
      "stage_type": "filter",
      "config": {
        "stage_id": "feature_search",
        "parameters": {
          "searches": [
            {
              "feature_uri": "mixpeek://image_extractor@v1/google_siglip_base_v1",
              "query": {
                "input_mode": "content",
                "value": "{{INPUT.query_image}}"
              },
              "top_k": 50
            }
          ]
        }
      }
    },
    {
      "stage_name": "filter",
      "stage_type": "reduce",
      "config": {
        "stage_id": "score_threshold",
        "parameters": {
          "min_score": "{{INPUT.min_similarity}}"
        }
      }
    }
  ]
}
```

## 6. Search

**With image URL:**

```bash theme={null}
POST /v1/retrievers/{retriever_id}/execute
{
  "inputs": {
    "query_image": "https://example.com/reference.jpg",
    "min_similarity": 0.75
  }
}
```

**With pre-computed embedding (faster):**

```bash theme={null}
POST /v1/retrievers/{retriever_id}/execute
{
  "inputs": {
    "embedding": [0.1, 0.2, ...]
  }
}
```

**With base64:**

```python theme={null}
import base64

with open("image.jpg", "rb") as f:
    image_data = base64.b64encode(f.read()).decode()

response = requests.post(
    "https://api.mixpeek.com/v1/retrievers/{retriever_id}/execute",
    json={
        "inputs": {
            "query_image": f"data:image/jpeg;base64,{image_data}"
        }
    }
)
```

## Cross-Modal Search (Image → Video)

Search videos using a reference image:

```bash theme={null}
{
  "stage_name": "cross_modal_search",
  "stage_type": "filter",
  "config": {
    "stage_id": "feature_search",
    "parameters": {
      "searches": [
        {
          "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
          "query": {
            "input_mode": "content",
            "value": "{{INPUT.query_image}}"
          },
          "top_k": 50
        }
      ]
    }
  }
}
```

## Multi-Collection Search

Search images and videos together:

```bash theme={null}
{
  "retriever_name": "visual-federated-search",
  "collection_identifiers": ["col_images", "col_videos"],
  "stages": [
    {
      "stage_name": "federated_search",
      "stage_type": "filter",
      "config": {
        "stage_id": "feature_search",
        "parameters": {
          "searches": [
            {
              "feature_uri": "mixpeek://image_extractor@v1/google_siglip_base_v1",
              "collections": ["col_images"],
              "weight": 0.5,
              "top_k": 25
            },
            {
              "feature_uri": "mixpeek://multimodal_extractor@v1/vertex_multimodal_embedding",
              "collections": ["col_videos"],
              "weight": 0.5,
              "top_k": 25
            }
          ],
          "fusion": "rrf"
        }
      }
    }
  ]
}
```

## Similarity Thresholds

| Score | Meaning |
| - | - |
| 0.95+ | Near-duplicate |
| 0.85-0.94 | Very similar |
| 0.70-0.84 | Related |
| Below 0.70 | Weak match |

## Classify with Taxonomies

Auto-tag assets by matching against a reference collection of known brands or product types:

```bash theme={null}
POST /v1/taxonomies
{
  "taxonomy_name": "brand-classifier",
  "config": {
    "taxonomy_type": "flat",
    "retriever_id": "ret_reverse_image_search",
    "input_mappings": [
      { "input_key": "query_image", "source_type": "payload", "path": "image_url" }
    ],
    "source_collection": {
      "collection_id": "col_product_images",
      "enrichment_fields": [
        { "field_path": "metadata.brand", "merge_mode": "enrich" }
      ]
    }
  }
}
```

New assets automatically get `metadata.brand` enriched when they visually match a known reference. See [Taxonomies](https://docs.mixpeek.com/docs/enrichment/taxonomies.md) for hierarchical taxonomies.

## Discover Clusters

Find visual themes across your asset library:

```bash theme={null}
POST /v1/clusters
{
  "cluster_name": "visual-themes",
  "collection_ids": ["col_product_images"],
  "cluster_type": "vector",
  "vector_config": {
    "feature_uris": ["mixpeek://image_extractor@v1/google_siglip_base_v1"],
    "clustering_method": "hdbscan",
    "algorithm_params": { "min_cluster_size": 10 },
    "preprocessing_steps": [
      { "method": "umap", "n_components": 2 }
    ]
  },
  "llm_labeling": {
    "provider": "openai",
    "model_name": "gpt-4o-mini"
  }
}
```

Clusters reveal groupings like "product close-ups", "lifestyle shots", and "packaging" without predefined categories. Promote stable clusters to taxonomy nodes. See [Clusters](https://docs.mixpeek.com/docs/enrichment/clusters.md) for all algorithms.

## Set Up Alerts

Get notified when new assets closely match existing ones (counterfeit detection, duplicate detection):

```bash theme={null}
POST /v1/alerts
{
  "name": "duplicate-detection",
  "retriever_id": "ret_reverse_image_search",
  "trigger_on": "results",
  "notification_config": {
    "channels": [
      { "channel_type": "webhook",
        "config": { "url": "https://example.com/webhook" } }
    ]
  }
}
```

A retriever-source alert fires on whatever its retriever returns, so scope the
match inside the retriever rather than on the alert. Set `trigger_on` to
`no_results` to fire when nothing matches. See [Alerts](https://docs.mixpeek.com/docs/enrichment/alerts.md).

## Set Up Webhooks

Track batch processing for large asset uploads:

```bash theme={null}
POST /v1/organizations/webhooks
{
  "webhook_name": "asset-processing",
  "event_types": ["objects.created.batch", "collection.documents.written"],
  "channels": [
    { "channel": "webhook", "configs": { "url": "https://example.com/webhook" } }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.