Reverse Image & Video Search

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

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}}"
        }
      }
    }
  ]
}

6. Search

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
    }
)

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
      }
    ]
  }
}

Multi-Collection Search

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

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

Tutorials

​Input Methods

​1. Create a Bucket

​2. Create a Collection

​3. Ingest Assets

​4. Process

​5. Create a Retriever

​6. Search

​Cross-Modal Search (Image → Video)

​Multi-Collection Search

​Similarity Thresholds

Input Methods

1. Create a Bucket

2. Create a Collection

3. Ingest Assets

4. Process

5. Create a Retriever

6. Search

Cross-Modal Search (Image → Video)

Multi-Collection Search

Similarity Thresholds