Image Matching

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:

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

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)


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).

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.

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
  }
}

Was this page helpful?