Search
Visual search
Die Dokumentation ist auf Englisch verfasst.
Auf dieser Seite
Let a shopper search by uploading a photo instead of typing. A vision model looks at the image and describes it with a handful of tags (colour, product type, material, style and so on), and those tags are then run as a normal search against the site's catalogue. This is not image similarity search: matching still happens on text, only on text the visitor never had to type.
The tags are written in the page's language, the one filter[lang] names, or
else in the first of the site's languages,
so they match the words of the catalogue they are searched in.
Base URL: https://searcio.com/api/v1/sites/{site}, or key-relative
https://searcio.com/api/v1, where the site is resolved from the search
key.
Authentication: the search key (?key=sk_… or X-Search-Key), as for
GET /search, and works only on the site's own domain.
POST /search/visual
A multipart/form-data request carrying one file field.
| Field | Type | Notes |
|---|---|---|
photo |
file | Required. An image, up to 8 MB. |
type |
string (≤ 255) | Only these content types, separated by commas, as on /search. Send type=product for a photo search in a shop, so pages do not come back. |
filter[field] |
string, or a list | The same filters as /search: a configured facet field or lang, as a query parameter beside key or as multipart fields. Send the page's filter[lang] on a multilingual shop; otherwise a photo taken on the English page also returns the German products. |
key |
string | The search key (or X-Search-Key). |
The site must have visual search turned on; see the
visual_search feature switch and
AI visual tagging. Visual search and visual
tagging are included in the same plans, but each has its own switch and its own
monthly allowance.
Example
curl -X POST "https://searcio.com/api/v1/sites/123/search/visual?key=sk_live_xyz" \
-F "photo=@dress.jpg"Response 200 OK
{
"query": "red silk dress",
"search_id": "9f1c2b7e-5f3a-4a1e-9d64-2f0c1b3a8e77",
"tags": ["red", "silk", "dress"],
"total": 1,
"hits": [
{
"id": "p-1",
"score": 4.2,
"source": { "title": "Red Silk Dress", "type": "product", "url": "/products/red-silk-dress" },
"highlight": null
}
],
"facets": {}
}hits and facets have exactly the same shape as in
GET /search, and search_id works the same way:
send it to /search/click when a visitor opens a
result. A photo search never triggers a
search redirect: redirects match terms a
visitor typed, and these tags are generated.
Empty results. When the vision model finds nothing worth tagging (a blurry photo, or one with nothing recognisable in it), the endpoint answers successfully with an empty result instead of an error:
{ "query": null, "tags": [], "total": 0, "hits": [], "facets": [] }Render it like any search without results, with a "No matches, try another photo" message rather than an error banner.
Errors
| Status | When |
|---|---|
401 |
Missing or invalid search key |
403 |
Site disabled, Origin not the site's own domain, or visual search is not turned on for this site |
422 |
photo is missing, is not an image, or exceeds 8 MB |
429 |
Monthly visual search quota reached ({ "metric": "visual_searches", "limit": N }) or rate limited |
The monthly quota is checked before the image is analysed, so a request over the quota never incurs the cost of the analysis. A successful photo search counts against both the visual search allowance and the site's normal search allowance, since a real catalogue search runs.
Frontend integration: a camera and upload button
This example needs no dependencies, only a file input, FormData and fetch.
On a phone, capture="environment" opens the camera directly instead of the
photo picker.
<input type="file" id="visual-search-input" accept="image/*" capture="environment" />
<ul id="visual-search-results"></ul>
<script>
const KEY = 'sk_live_xyz';
const BASE = 'https://searcio.com/api/v1/sites/123';
const input = document.getElementById('visual-search-input');
const results = document.getElementById('visual-search-results');
input.addEventListener('change', async () => {
const photo = input.files[0];
if (!photo) return;
results.innerHTML = '<li>Searching…</li>';
const body = new FormData();
body.append('photo', photo);
const response = await fetch(`${BASE}/search/visual?key=${KEY}`, {
method: 'POST',
body,
});
if (!response.ok) {
results.innerHTML = '<li>Sorry, that search failed. Try another photo.</li>';
return;
}
const data = await response.json();
if (data.hits.length === 0) {
results.innerHTML = '<li>No matches for that photo - try a clearer shot.</li>';
return;
}
results.innerHTML = data.hits
.map((hit) => `<li><a href="${hit.source.url}">${hit.source.title}</a></li>`)
.join('');
});
</script>- No debouncing needed: the request is sent once per selected file, not per keystroke.
- Put the search key in the query string, not in
X-Search-Key: as with every endpoint called from the browser, CORS is resolved from?key=(see CORS), so the request works whether or not the browser sends a preflight. - Degrade gracefully: hide the upload button when
/storefront-configdoes not report visual search, so shoppers on a plan without it never see a control that could only answer403.