Loading...
searchstack.dev
Sign In

Image search

Image search finds the records in a list or group that look most like a picture you supply. Instead of matching words, the image is turned into a vector — the same kind of numeric fingerprint semantic text search uses — and compared against the vectors of your indexed records. So a photo of a red trainer comes back next to other red trainers, even when nothing in the query or the records says “red” or “trainer”.

It is the engine behind “search by photo”, “shop the look” and “more like this”, and it runs alongside the normal text endpoints — the same list serves both. This is an API feature: there is no console screen for it, so the worked requests below are the reference.

Two ways to supply the image
  • By URL (image_path) — pass an absolute, publicly reachable image URL. Best when the image is already hosted — a product photo, a CMS asset.
  • By base64 (image_base64) — send the raw image bytes base64-encoded. Best for camera uploads and files you don’t want to expose at a public URL.

URL requests come in a GET form (the image reference in the query string) and a POST form (a JSON body, which also carries the optional knobs below). Base64 requests are POST-only for a list; only the group base64 variant also has a GET form. All the paths live under /search/images.

Search a list by image URL
GET https://api.searchstack.dev/search/images/{account}/{list}/{version}?image_path={image url}
Search a group by image URL

Just like text search, an image query can fan out across every list in a group. Supply the group’s membership version in the path, exactly as for a list:

GET https://api.searchstack.dev/search/images/group/{account}/{group}/{version}?image_path={image url}
Search with a base64 image, and tune the match

POST the encoded bytes so the image never has to be hosted. The POST body also accepts the same options a text search takes — a filter over facet fields, size/skip for paging, and minimum_image_score to drop weak visual matches (raise it to return only close looks, lower it to widen the net):

POST https://api.searchstack.dev/search/images/base64/{account}/{list}/{version}

{
  "image_base64": "<base64-encoded image bytes>",
  "filter": "in_stock eq true",
  "minimum_image_score": 0.7,
  "size": 20
}

The URL variants have matching POST forms (image_path in the body) that take the same options, and groups have base64 variants too. The good value for minimum_image_score depends on your model and images — start without it, then tune.

Response

The response is the same shape as a text search: a ranked results array ordered by visual similarity — closest first, each hit scored under @image_score with your own fields under fields:

{
  "results": [
    { "name": "aero-runner-crimson", "list_name": "products", "@image_score": 0.92, "fields": { "colour": "red",  "image_url": "https://cdn.acme.example/aero-crimson.jpg" } },
    { "name": "track-star-scarlet",  "list_name": "products", "@image_score": 0.88, "fields": { "colour": "red",  "image_url": "https://cdn.acme.example/track-scarlet.jpg" } },
    { "name": "aero-runner-slate",   "list_name": "products", "@image_score": 0.74, "fields": { "colour": "grey", "image_url": "https://cdn.acme.example/aero-slate.jpg" } }
  ],
  "count": 3,
  "total_count": 3,
  "query_id": "5c1e9be04d0f4f1c9a2b7d6e8f301a2b"
}
When to use it
  • E-commerce “shop the look” and “find similar” features.
  • Visual de-duplication — checking whether a picture already exists in a catalogue.
  • Media libraries whose assets have little or no text to search on.
What it needs

Image search works when the list’s embedding model produces image vectors (a multimodal model), and your records carry image URLs — typically a resource field pointing at pictures in a media store. Index those records once and the same list answers both text and image queries.

A worked example

A shoe shop has a products list whose records carry an image_url resource field, indexed with a multimodal model. A shopper snaps a photo of a red trainer in the wild and your app POSTs it, base64-encoded, to /search/images/base64/acme/products/3 with "filter": "in_stock eq true" and "minimum_image_score": 0.7. Back comes a ranked list of the shop’s closest-looking in-stock trainers — reds first, then near-reds — each with the image_url your page needs to render the result. No tags, no text, no manual curation: the picture did the searching.

Top