Image Matching
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 endpoint 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)
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
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"
}
}
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
andphash
).
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
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"
}
}
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
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
}
}
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
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
}
}