Skip to main content
Reverse media search uses the warehouse’s Decompose layer to extract visual features, then queries them in the Reassemble layer. See Multi-Stage Retrieval for composing pipelines.

​
Input Methods

MethodExampleSpeed
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

POST /v1/buckets
{
  "bucket_name": "visual-assets",
  "schema": {
    "properties": {
      "asset_url": { "type": "url", "required": true },
      "brand": { "type": "text" },
      "campaign_id": { "type": "text" }
    }
  }
}

​
2. Create a Collection

For images: 
POST /v1/collections
{
  "collection_name": "product-images",
  "source": { "type": "bucket", "bucket_id": "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: 
POST /v1/collections
{
  "collection_name": "video-segments",
  "source": { "type": "bucket", "bucket_id": "bkt_visual_assets" },
  "feature_extractor": {
    "feature_extractor_name": "video_extractor",
    "version": "v1",
    "input_mappings": { "video_url": "asset_url" },
    "parameters": {
      "scene_detection_threshold": 0.3,
      "extract_keyframes": true
    }
  }
}

​
3. Ingest Assets

POST /v1/buckets/{bucket_id}/objects
{
  "key_prefix": "/products/shoes",
  "metadata": {
    "asset_url": "s3://my-bucket/products/sneaker-001.jpg",
    "brand": "Nike",
    "campaign_id": "fall-2025"
  }
}

​
4. Process

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

POST /v1/retrievers
{
  "retriever_name": "reverse-image-search",
  "collection_ids": ["col_product_images"],
  "input_schema": {
    "properties": {
      "query_image": { "type": "image", "required": true },
      "min_similarity": { "type": "number", "default": 0.7 }
    }
  },
  "stages": [
    {
      "stage_name": "visual_search",
      "version": "v1",
      "parameters": {
        "feature_searches": [
          {
            "feature_uri": "mixpeek://image_extractor@v1/image_embedding",
            "query": {
              "input_mode": "content",
              "content": { "url": "{{INPUT.query_image}}" }
            },
            "top_k": 50
          }
        ]
      }
    },
    {
      "stage_name": "filter",
      "version": "v1",
      "parameters": {
        "filters": {
          "field": "_score",
          "operator": "gte",
          "value": "{{INPUT.min_similarity}}"
        }
      }
    }
  ]
}
With image URL: 
POST /v1/retrievers/{retriever_id}/execute
{
  "inputs": {
    "query_image": "https://example.com/reference.jpg",
    "min_similarity": 0.75
  },
  "limit": 10
}
With pre-computed embedding (faster): 
POST /v1/retrievers/{retriever_id}/execute
{
  "inputs": {
    "embedding": [0.1, 0.2, ...]
  },
  "limit": 10
}
With base64: 
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}"
        },
        "limit": 10
    }
)

​
Cross-Modal Search (Image → Video)

Search videos using a reference image: 
{
  "stage_name": "cross_modal_search",
  "version": "v1",
  "parameters": {
    "feature_searches": [
      {
        "feature_uri": "mixpeek://video_extractor@v1/scene_embedding",
        "query": {
          "input_mode": "content",
          "content": { "url": "{{INPUT.query_image}}" }
        },
        "top_k": 50
      }
    ]
  }
}
Search images and videos together: 
{
  "retriever_name": "visual-federated-search",
  "collection_ids": ["col_images", "col_videos"],
  "stages": [
    {
      "stage_name": "federated_search",
      "version": "v1",
      "parameters": {
        "feature_searches": [
          {
            "feature_uri": "mixpeek://image_extractor@v1/image_embedding",
            "collections": ["col_images"],
            "weight": 0.5,
            "top_k": 25
          },
          {
            "feature_uri": "mixpeek://video_extractor@v1/scene_embedding",
            "collections": ["col_videos"],
            "weight": 0.5,
            "top_k": 25
          }
        ],
        "fusion_method": "rrf"
      }
    }
  ]
}

​
Similarity Thresholds

ScoreMeaning
0.95+Near-duplicate
0.85-0.94Very similar
0.70-0.84Related
Below 0.70Weak match

​
Classify with Taxonomies

Auto-tag assets by matching against a reference collection of known brands or product types: 
POST /v1/taxonomies
{
  "taxonomy_name": "brand-classifier",
  "taxonomy_type": "flat",
  "retriever_id": "ret_reverse_image_search",
  "collection_id": "col_product_images",
  "input_mappings": [{ "source": "payload.asset_url", "target": "query_image" }],
  "enrichment_fields": [{ "source": "payload.brand", "target": "detected_brand" }],
  "threshold": 0.8,
  "execution_mode": "materialize"
}
New assets automatically get detected_brand enriched when they visually match a known reference. See Taxonomies for hierarchical taxonomies.

​
Discover Clusters

Find visual themes across your asset library: 
POST /v1/clusters
{
  "cluster_name": "visual-themes",
  "collection_id": "col_product_images",
  "feature_uri": "mixpeek://image_extractor@v1/image_embedding",
  "algorithm": { "name": "hdbscan", "params": { "min_cluster_size": 10 } },
  "llm_labeling": { "enabled": true },
  "dimension_reduction": { "method": "umap", "n_components": 2 }
}
Clusters reveal groupings like “product close-ups”, “lifestyle shots”, and “packaging” without predefined categories. Promote stable clusters to taxonomy nodes. See Clusters for all algorithms.

​
Set Up Alerts

Get notified when new assets closely match existing ones (counterfeit detection, duplicate detection): 
POST /v1/alerts
{
  "alert_name": "duplicate-detection",
  "collection_id": "col_product_images",
  "condition": { "field": "taxonomy.detected_brand", "operator": "exists" },
  "notification": { "type": "webhook", "url": "https://example.com/webhook" }
}

​
Set Up Webhooks

Track batch processing for large asset uploads: 
POST /v1/webhooks
{
  "webhook_name": "asset-processing",
  "url": "https://example.com/webhook",
  "events": ["batch.completed", "batch.failed"]
}