Image Search

Image-based product discovery

Search products by image URL

get

Searches for products similar to the provided image using an external search service. The image is fetched from the provided URL and analyzed for visual similarity with indexed product images.

This endpoint requires the external search extension to be enabled through the EXTERNAL_SEARCH_EXTENSION_CONFIG dynamic setting. When disabled, this endpoint returns a 404 Not Found response.

The search can be refined by providing optional text keywords and excluding specific product identifiers from the results.

Rate limiting applies to prevent abuse of this endpoint.

Image Requirements:

• Image must be accessible via the provided URL

• Image dimensions must be less than the configured maximum (default: 2000x2000 pixels)

Query parameters

urlstring · uriRequired

URL of the image to search for

Example: https://example.com/product-image.jpg

excluded_product_idsstringOptional

Comma-separated list of product identifiers to exclude from results

Example: 1,2,3

textstring · max: 5000Optional

Optional text keywords to refine the image search

Example: red dress

Responses

200

Image search completed successfully

application/json

Image search results

product_idsinteger[]Required

List of product identifiers matching the image

Example: [123,456,789]

400

Request validation error

application/json

404

External search extension not enabled

application/json

429

Too many requests

application/json

500

Internal server error

application/json

get

/image-search/

HTTPcURLJavaScriptPython

GET /image-search/?url=https%3A%2F%2Fexample.com%2Fproduct-image.jpg HTTP/1.1
Host: sandbox.akinon.com
Accept: */*

{
  "product_ids": [
    123,
    456,
    789
  ]
}

Search products by base64 image

post

Searches for products similar to the provided base64-encoded image using an external search service. The image is decoded and analyzed for visual similarity with indexed product images.

This endpoint requires the external search extension to be enabled through the EXTERNAL_SEARCH_EXTENSION_CONFIG dynamic setting. When disabled, this endpoint returns a 404 Not Found response.

The search can be refined by providing optional text keywords and excluding specific product identifiers from the results.

Rate limiting applies to prevent abuse of this endpoint.

Image Requirements:

• Image must be valid base64-encoded data

• Image must be a valid image format (JPEG, PNG, JPG, WEBP.)

• Image file size must not exceed the configured maximum (default: 5MB)

• Image dimensions must be less than the configured maximum (default: 2000x2000 pixels)

Body

application/json

Request payload for base64 image search

imagestringRequired

Base64-encoded image data. Must be a valid image format (JPEG, PNG, etc.). The decoded image must be smaller than the configured maximum file size and have dimensions less than the configured maximum.

Example: iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAG0lEQVR4nGI5dmmmkgwXc/S6b9fEAwEBAAD//ynVBb51hF0FAAAAAElFTkSuQmCC

excluded_product_idsinteger[]Optional

Product identifiers to exclude from results

Example: [1,2,3]

textstring · max: 5000Optional

Optional text keywords to refine the image search

Example: red dress

Responses

200

Image search completed successfully

application/json

Image search results

product_idsinteger[]Required

List of product identifiers matching the image

Example: [123,456,789]

400

Request validation error

application/json

404

External search extension not enabled

application/json

429

Too many requests

application/json

500

Internal server error

application/json

post

/image-search/

HTTPcURLJavaScriptPython

POST /image-search/ HTTP/1.1
Host: sandbox.akinon.com
Content-Type: application/json
Accept: */*
Content-Length: 174

{
  "image": "iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAAG0lEQVR4nGI5dmmmkgwXc/S6b9fEAwEBAAD//ynVBb51hF0FAAAAAElFTkSuQmCC",
  "excluded_product_ids": [
    1,
    2,
    3
  ],
  "text": "red dress"
}

{
  "product_ids": [
    123,
    456,
    789
  ]
}