Image Matching

Quickstart Blog Test in App Similarity Demo

To access the Ximilar API, first register at Ximilar App to get your API token. The API follows the general rules as described in the First Steps.

The Image Matching API identifies duplicate and near-duplicate images by extracting and comparing their visual hashes. It recognizes similar images, including slightly modified ones (changes in color (B/W), resolution, compression, or added noise).

This solution enables you to:

Identify and remove duplicates
Group related images from different sources, including user-generated or low-quality content
Assign tags or existing product data to new items based on similarity

It is particularly useful for managing large image collections that cannot be sorted manually.

How it Works

The Image Matching service works as follows:

Calculate visual hash – Generates a unique hash representing each image’s visual content.
Compare hashes – Identifies duplicate or near-duplicate images by comparing hashes.
Rank images – Optionally ranks images based on similarity to a query image.

Visual search solutions always operate on a specific image collection. To test similarity, try the Product Similarity demo on our fashion collection. To create your own collection, go to Ximilar App and select Image Similarity: Collections → Image Matching

Endpoints

The base URL for this service is:

https://api.ximilar.com/image_matching/v2/<method>

The currently available endpoints are:

https://api.ximilar.com/image_matching/v2/ping  (test the service and get basic info)
https://api.ximilar.com/image_matching/v2/visual_hash  (get visual hash for image(s))
https://api.ximilar.com/image_matching/v2/remove_duplicates  (merge matching images/records)
https://api.ximilar.com/image_matching/v2/rank_images  (rank images/records against query image)

POST/v2/ping

Ping

Test the service and get basic information about it.

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN.

Response fields

Name
_service_info
Type
object
Description
Information about the service.
Name
_service_info._name
Type
string
Description
Name of the service.
Name
_service_info._info
Type
string
Description
Description of the service.

Request

POST

/v2/ping

curl --request POST \
  --url https://api.ximilar.com/image_matching/v2/ping \
  --header 'authorization: Token __API_TOKEN__'

Response

{
  "status": {
    "code": 200,
    "text": "OK"
  },
  "_service_info": {
    "_name": "Image matching service",
    "_info": "Get visual hashes, find (near-)duplicate images and rank them"
  }
}

POST/v2/visual_hash

Visual Hash

Get a visual hash (or several different types of hashes) for an image or a list of images.

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN.

Request parameters

Name
records
Type
array
Max
Maximum:10
Description
List of photos to get hashes for. Each record represents a single image.
Name
records[]._url
Type
string
Description
URL with a PNG, JPG, or TIFF image file.
Name
records[]._base64
Type
string
Description
Base64-encoded content of a PNG, JPG or TIFF image file.
Name
hash_type
Type
string
Default
Default:bmh1 AND phash
Description
Type of visual hash to compute (default: both bmh1 and phash).

Response fields

Name
records
Type
array
Description
An array of records with computed hashes.
Name
records[].bmh1
Type
string
Description
Binary matrix hash.
Name
records[].phash
Type
string
Description
Perceptual hash.

Request

POST

/v2/visual_hash

curl --request POST \
  --url https://api.ximilar.com/image_matching/v2/visual_hash \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{
  "records": [
    {"_url": "https://images.ximilar.com/examples/fashion_products/10073009-HERO.jpeg"}
  ]
}'

Response

{
  "records": [
    {
      "_url": "https://images.ximilar.com/examples/fashion_products/10073009-HERO.jpeg",
      "_width": 400,
      "_height": 400,
      "bmh1": "11111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111111001111111111111111111111111111110000111111111111111101111111111110001111111101111111000000001111110011111111001111110000000011111110111111110001111100000000111111111111111100001111000000001111111111111111000001111000000011111111111111110000001110000000111111111111111100000001100000001111111101111111000000001000000011111111001111110000000010000000111111110001111100000000100000001111111100001111000000001100000011111111000001110000000000000000111111110000001100000000000000001100000000000001000000000000000011000000000000000000000000000000001000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000001001100000000000001110000000000011111111000000000111111110000000001",
      "phash": "1111110000001011010000111110110010111001000101100010010110001010"
    }
  ],
  "statistics": {
    "processing time": 0.13515067100524902
  },
  "status": {
    "code": 200,
    "text": "OK"
  }
}

POST/v2/remove_duplicates

Remove Duplicates

Merge the matching images/records (based on visual hashes).

When two or more records are matched, they are moved to the field removed_records of the first record.

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN.

Request parameters

Name
records
Type
array
Description
List of photos to merge.
Name
records[]._url
Type
string
Description
URL with a PNG, JPG, or TIFF image file.
Name
records[]._base64
Type
string
Description
Base64-encoded content of a PNG, JPG or TIFF image file.
Name
hash_type
Type
string
Default
Default:bmh1
Description
Type of visual hash to use for comparison (default: bmh1, optional: phash).
Name
range
Type
number
Default
Default:0
Description
Minimum threshold value for clustering (default: 0).

Response fields

Name
records
Type
array
Description
An array of records with merged duplicates.
Name
records[].removed_records
Type
array
Description
An array of records that were merged with this record.

Request

POST

/v2/remove_duplicates

curl --request POST \
  --url https://api.ximilar.com/image_matching/v2/remove_duplicates \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{
  "records": [
    {"_url": "__URL_PATH_1__", "_id": 1},
    {"_url": "__URL_PATH_1__", "_id": 2},
    {"_url": "__URL_PATH_2__", "_id": 3}
  ]
}'

Response

{
  "records": [
    {
      "_url": "__URL_PATH_1__",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "7a1cf0ee-a2dd-4fa2-9927-69441bc1d3dc"
      },
      "_id": "1",
      "_width": 259,
      "_height": 460,
      "removed_records": [
        {
          "_url": "__URL_PATH_1__",
          "_status": {
            "code": 200,
            "text": "OK",
            "request_id": "7a1cf0ee-a2dd-4fa2-9927-69441bc1d3dc"
          },
          "_id": "2",
          "_width": 259,
          "_height": 460
        }
      ]
    },
    {
      "_url": "__URL_PATH_2__",
      "_status": {
        "code": 200,
        "text": "OK",
        "request_id": "7a1cf0ee-a2dd-4fa2-9927-69441bc1d3dc"
      },
      "_id": "3",
      "_width": 212,
      "_height": 289
    }
  ],
  "status": {
    "code": 200,
    "text": "OK",
    "request_id": "7a1cf0ee-a2dd-4fa2-9927-69441bc1d3dc",
    "proc_id": "d9ac827a-ee8e-4e3b-a5d2-665c10e3fa84"
  },
  "statistics": {
    "processing time": 0.7242739200592041
  }
}

POST/v2/rank_images

Rank Images

Rank the images/records against the query image, based on their visual hashes.

The request contains records and query_record fields and returns query_records and answer_records. This is because we imitate the ranking endpoint of our ready-to-use services, such as Product and Photo Similarity.

Required attributes

Name
Authorization
Type
string
Description
Your API token in the format: Token YOUR_API_TOKEN.

Request parameters

Name
query_record
Type
object
Description
Record containing the image to compare against.
Name
query_record._url
Type
string
Description
URL with a PNG, JPG, or TIFF image file.
Name
query_record._base64
Type
string
Description
Base64-encoded content of a PNG, JPG or TIFF image file.
Name
records
Type
array
Description
List of images to rank.
Name
hash_type
Type
string
Default
Default:bmh1
Description
Type of visual hash to use for comparison (default: bmh1, optional: phash).

Response fields

Name
query_records
Type
array
Description
The query record(s) copied from the request.
Name
answer_records
Type
array
Description
Sorted array of records (first is the most matching).
Name
answer_distances
Type
array
Description
An array of distance values corresponding to answer_records.
Name
skipped_records
Type
array
Description
Records that failed analysis.

Request

POST

/v2/rank_images

curl --request POST \
  --url https://api.ximilar.com/image_matching/v2/rank_images \
  --header 'authorization: Token __API_TOKEN__' \
  --header 'content-type: application/json' \
  --data '{
  "query_record": {
    "_url": "__URL_PATH_1__"
  },
  "records": [
    {"_url": "__URL_PATH_1__"},
    {"_url": "__URL_PATH_2__"},
    {"_url": "__URL_PATH_3__"},
    {"_url": "__URL_PATH_4_NOT_WORKING__"}
  ]
}'

Response

{
  "query_records": [
    {
      "_url": "__URL_PATH_1__",
      "_width": 259,
      "_height": 460
    }
  ],
  "answer_distances": [0.0, 0.1, 26.0],
  "answer_records": [
    {
      "_url": "__URL_PATH_1__",
      "_id": "e7ee2a82-495f-4df7-adc3-5cdb2b5fadf7",
      "_width": 259,
      "_height": 460
    },
    {
      "_url": "__URL_PATH_2__",
      "_id": "b170de44-75e2-4c4c-a41a-ff1ed9fa84b6",
      "_width": 259,
      "_height": 460
    },
    {
      "_url": "__URL_PATH_3__",
      "test": "insomnia",
      "_id": "ee72be0b-ab93-4696-9689-7f866ea9bb38",
      "_width": 212,
      "_height": 289
    }
  ],
  "skipped_records": [
    {
      "_url": "__URL_PATH_4_NOT_WORKING__",
      "_status": {
        "code": 400,
        "text": "Error Loading Image: Unable to download image from '__URL_PATH_4_NOT_WORKING__', Attempts: 3",
        "request_id": "a798e682-2b89-49ea-bb6b-0c2d09d523c1"
      },
      "_id": "dccb8eab-c4da-4fc6-b24a-1d92fe96f75e"
    }
  ],
  "status": {
    "code": 300,
    "text": "MIXED_RESULT",
    "request_id": "a798e682-2b89-49ea-bb6b-0c2d09d523c1",
    "proc_id": "19ef9e49-0c6b-4dca-a52a-80726da178ed"
  },
  "statistics": {
    "processing time": 0.9733231067657471
  }
}