Overview
Use the Visual Similarity Search API to retrieve products similar to a provided image.
Parameters
Two parameters are required: the website token (token) and the image encoded as a base64 string (image). You can also use additional parameters accepted by the Search API.
Reuse an image with image_cache
The returned data structure is similar to that of the Search API, but includes an image_cache field. This field lets Athena XAI fetch the image from the cache, which reduces data transfer.
To use it, send the image_cache value as the image parameter in later requests for the same image.
Endpoint
| Method | Path |
|---|---|
POST | /api/v1/visual-similarity-search |
Request body
{
"token": "{{ website_token }}", //required
"image": "iVBORw0KGgoAAAANSUhEUgAAAyAAAAH0CAIA…" //required, image as a base64 string
}Successful response
{
"data": {
"products": {
"results": [
{
"short_description": null,
"salable_qty": 400,
"link": "https://m.com/apollo-running-short.html",
"description": "product description",
"availability": 1,
"configurable_options": [
{
"attribute_id": 93,
"options": [
{
"option_label": "Black",
"hash_code": "#000000",
"option_type": "1",
"option_id": "49",
"seo_value": "black"
}
],
"attribute_code": "color"
}
],
"price": {
"regular_price": 32.5,
"regular_price_with_currency": "$32.50",
"special_price": null,
"special_price_with_currency": null,
"loyalty_price": null,
"loyalty_price_with_currency": null,
"discount_percentage": 0
},
"id": 898,
"sku": "MSH02",
"views": 0,
"image": "https://m.com/media/catalog/product/main_1.jpg",
"meta_title": null,
"product_type_id": "configurable",
"meta_description": null,
"product_combinations": [
{
"color": "49",
"size": "175"
}
],
"name": "Apollo Running Short",
"child_products": [
{
"image": "https://m.com/media/catalog/product/main_1.jpg",
"stock_status": true,
"color": "49",
"size": "175",
"hover_image": "https://m.com/media/catalog/product/main_1.jpg",
"configurable_options": [
{
"type": "color",
"value": "49"
},
{
"type": "size",
"value": "175"
}
],
"entity_id": "894",
"sku": "MSH02-32-Black"
}
],
"type": "product",
"category_ids": [
19,
13
]
}
],
"amounts": {
"current_page": 1,
"last_page": 1,
"from": 1,
"to": 6,
"per_page": 15,
"next_page": null,
"prev_page": null,
"total": 6
},
"active_filters": [],
"filters": [
{
"title": "Category",
"type": "category1",
"array": [
{
"option_value": "11",
"option_key": "category1",
"option_label": "Men",
"selected": false,
"count": 1,
"type_id": "0",
"hax_code": null,
"url": "https://m.com/athena/?category1=11",
"url_path": "/?category1=11",
"url_params": {
"category1": "11"
}
]
},
{
"title": "Price",
"type": "pri",
"array": [
{
"option_value": " Less than $5",
"option_key": "pri",
"option_label": " Less than $5",
"selected": false,
"count": 0,
"type_id": "0",
"hax_code": null,
"url": "https://m.com/athena/?pri=+Less+than+$5",
"url_path": "/?pri=+Less+than+$5",
"url_params": {
"pri": "+Less+than+$5"
}
}
]
},
{
"title": "Material",
"type": "material",
"array": [
{
"option_value": "142",
"option_key": "material",
"option_label": "Cocona® performance fabric",
"selected": false,
"count": 2,
"type_id": "0",
"hax_code": null,
"url": "https://m.com/athena/?material=142",
"url_path": "/?material=142",
"url_params": {
"material": "142"
}
}
]
},
{
"title": "Size",
"type": "size",
"array": [
{
"option_value": "171",
"option_id": "171",
"option_key": "size",
"option_label": "28",
"attribute_id": 144,
"selected": false,
"count": 5,
"type_id": "0",
"hax_code": "",
"url": "https://m.com/athena/?size=171",
"url_path": "/?size=171",
"url_params": {
"size": "171"
}
}
]
}
],
"sorters": [
{
"option_key": "product_list_order",
"option_value": "relevance",
"option_label": "Relevance",
"url": "https://m.com/athena/?product_list_order=relevance",
"url_path": "/?product_list_order=relevance",
"url_params": {
"product_list_order": "relevance"
},
"selected": true
}
],
"orders": [
{
"option_key": "product_list_limit",
"option_value": 15,
"option_label": "15",
"url": "https://m.com/athena/?product_list_limit=15",
"url_path": "/?product_list_limit=15",
"url_params": {
"product_list_limit": "15"
},
"selected": true
}
],
"pager": [],
"collection_price": {
"lowest_price_with_filters": 32.5,
"highest_price_with_filters": 45,
"lowest_price": 32.5,
"highest_price": 45
},
"visual_filter": []
},
"modes": [
{
"name": "Grid",
"type": "grid",
"option_key": "product_list_mode",
"option_value": "grid",
"option_label": "Grid",
"url": "https://m.com/athena/?product_list_mode=grid",
"url_path": "/?product_list_mode=grid",
"url_params": {
"product_list_mode": "grid"
},
"selected": true
},
{
"name": "List",
"type": "list",
"option_key": "product_list_mode",
"option_value": "list",
"option_label": "List",
"url": "https://m.com/athena/?product_list_mode=list",
"url_path": "/?product_list_mode=list",
"url_params": {
"product_list_mode": "list"
}
}
],
"query": null,
"suggested_text": null,
"used_suggestions": false,
"blog": {
"results": [],
"amounts": {
"current_page": 1,
"last_page": 1,
"from": null,
"to": null,
"per_page": 15,
"next_page": null,
"prev_page": null,
"total": 0
},
"orders": [
{
"option_key": "product_list_limit",
"option_value": 15,
"option_label": "15",
"url": "https://m.com/athena/?product_list_limit=15",
"url_path": "/?product_list_limit=15",
"url_params": {
"product_list_limit": "15"
},
"selected": true
}
],
"pager": []
},
"banners": [
{
"html": "banner_content"
}
],
"current_url": "https://example.com/athena/?q=",
"current_path": "",
"image_cache": "d17730a78f8fe3c3c4f5049fa0e0a536"
}
}