SearchPixel API Documentation

Welcome to SearchPixel — an AI-powered visual and semantic product search engine. Built on CLIP ViT-L/14 (image embeddings) and BGE base (text embeddings), running on RTX 6000 Ada GPU infrastructure in our Indian datacenter.

Status: Open beta. Read endpoints on the demo store work without a key so you can try queries from the homepage. Write endpoints (/index, /product/<id> DELETE) require a real API key — request one from [email protected].

Authentication

SearchPixel reuses your PixelAPI key — same dashboard, same key. Either header works:

Authorization: Bearer YOUR_PIXELAPI_KEY
# or
X-API-Key: YOUR_PIXELAPI_KEY

Your store_id is derived from your account: user 42 ⇒ u42. You can't read or write any store other than your own (or the public demo store, which is read-only).

Missing or wrong key on a write endpoint returns HTTP 401. Blocked accounts return HTTP 403.

Base URL

https://searchpixel.pixelapi.dev

GET /health

Check API server health and model status.

GET /health
Returns server status, GPU info, and loaded model states.

Response:

{ "status": "ok", "clip_loaded": true, "bge_loaded": true, "gpu_available": true, "gpu_name": "NVIDIA RTX 6000 Ada Generation", "gpu_memory_used_mb": 2060.57, "stores_active": 2 }

GET /search

Text-based semantic product search. Works with either store_id (authenticated) or store_id=demo (public demo).

GET /search?q={query}&top_k={k}&store_id={store_id}
ParameterTypeDescription
q requiredstringNatural language search query
top_kintegerNumber of results to return (default: 5, max: 50)
store_idstringYour store ID (default: demo for public testing)
search_typestringtext | visual | hybrid (default: hybrid)
hybrid_weightfloatWeight for text search in hybrid mode, 0.0–1.0 (default: 0.5)
min_scorefloatMinimum relevance score threshold, 0.0–1.0 (default: 0.0)

Example:

curl "https://searchpixel.pixelapi.dev/search?q=red%20silk%20saree%20for%20wedding&top_k=5&store_id=demo"

Response:

{ "query": "red silk saree for wedding", "search_type": "hybrid", "total_results": 5, "results": [ { "product_id": "prod_001", "name": "Saree Gold Silk Wedding Party Traditional", "description": "Elegant gold silk saree perfect for weddings and festive occasions", "category": "Sarees", "price": 1999, "currency": "INR", "rank": 1, "score": 0.706 }, ... ] }

POST /search

Hybrid search — combine text query with an optional image for more precise results.

POST /search
Send JSON with query, optional query_image (base64), and store_id.
FieldTypeDescription
querystringText search query
query_imagestring (base64)Optional: base64-encoded image for visual search
store_idstringYour store ID
top_kintegerMax results (default: 5)
search_typestringhybrid uses both signals; visual uses only image
hybrid_weightfloat0.0=text-only, 1.0=visual-only (default: 0.5)

Example:

curl -X POST https://searchpixel.pixelapi.dev/search \ -H "Content-Type: application/json" \ -d '{ "query": "find something like this but in blue", "query_image": "'$(base64 -w0 shirt.jpg)'", "store_id": "demo", "top_k": 5 }'

POST /index

Add a single product to your store's search index.

POST /index
{ "store_id": "my_shop", "product": { "product_id": "SKU-12345", "name": "Men's Navy Blue Cotton Kurta", "description": "Comfortable navy blue cotton kurta for daily wear. Machine washable.", "category": "Kurtas", "price": 799, "currency": "INR", "image_url": "https://yourstore.com/images/kurta-navy.jpg" } }

Response: { "indexed": true, "product_id": "SKU-12345" }

POST /index/image

Upload a product image file and index it. Accepts multipart/form-data.

POST /index/image
curl -X POST https://searchpixel.pixelapi.dev/index/image \ -F "store_id=demo" \ -F "product_id=prod_001" \ -F "name=Saree Gold Silk" \ -F "description=Elegant gold silk saree" \ -F "category=Sarees" \ -F "price=1999" \ -F "[email protected]"

DELETE /product/{product_id}

Remove a product from the search index.

DELETE /product/{product_id}?store_id={store_id}

GET /stores

List all stores in your account and their product counts.

GET /stores?api_key={your_api_key}

Shopify Integration

Install the SearchPixel app from the Shopify App Store, connect your store, and your entire product catalog is indexed automatically within minutes.

How it works

  1. Install SearchPixel from Shopify App Store
  2. Authorize the app to read your product data
  3. We fetch all products, generate CLIP + BGE embeddings
  4. Add a "SearchPixel" section to your theme
Coming soon: Shopify app is in private beta. Request early access.

WooCommerce Integration

Install the SearchPixel WordPress plugin and connect with your WooCommerce store.

# Install via WordPress admin # 1. Download the SearchPixel WooCommerce Plugin # 2. Upload to /wp-content/plugins/searchpixel/ # 3. Activate and add your API key # 4. Click "Sync Catalog" to index all products
Coming soon: WooCommerce plugin is in development. ETA: June 2026.

Web Widget Integration

Add a universal JavaScript search widget to any website — custom Shopify, WooCommerce, or any HTML site.

<!-- Add this one line to your website's <body> --> <script src="https://cdn.searchpixel.dev/widget/v1.js" data-api-key="YOUR_PIXELAPI_KEY" data-store-id="your_store_id"></script>

This automatically adds a floating search button to your site. Customize it by adding a data-theme attribute: light, dark, or auto.

Pricing Configuration

SearchPixel includes a built-in price filter that leverages semantic understanding:

# Natural language price filtering works automatically: # "laptop under 50000" — correctly filters to sub-₹50,000 laptops # "gift for wife under 2000 rupees" — understands price constraint # "cheap summer dresses below 1000" — semantic price parsing

For explicit price ranges, pass price_min and price_max in your search request:

{ "query": "cotton shirt", "price_min": 500, "price_max": 1500, "store_id": "my_shop" }

How Embeddings Work

SearchPixel uses two AI models working together:

1. CLIP (Visual + Text) — Converts images and text into the same 768-dimensional vector space. "A red silk saree" and an actual saree photo land near each other in this space. Powered by ViT-L/14.

2. BGE-M3 (Text Enhancement) — Understands natural language meaning, context, synonyms, and intent. Converts your search query into a 1024-dimensional semantic embedding. Used alongside CLIP for hybrid search.

Hybrid scoring: Final score = 0.5 × CLIP_score + 0.5 × BGE_score with min-max normalization applied to each model's raw cosine distances before combining.

Questions? Email [email protected] · Home · Pricing