Image Matching

Quickstart Blog Test in APP Public Demo

The Image Matching service can identify duplicate or near-duplicate images. It calculates a "visual hash" that should be the same or nearly the same for images that are only slightly modified: shift of colors (B/W), re-compression, change of resolution, noise etc.

The API follows the general rules of Ximilar API as described in the First Steps section.

How It Works

The Image Matching service works through the following process:

Calculate Visual Hash: The service calculates a unique visual hash for each image that represents its visual content.
Compare Hashes: By comparing these hashes, the service can identify duplicate or near-duplicate images.
Rank Images: You can also rank images based on their similarity to a query image.

Endpoints

The base URL for this service is:

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

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 given image(s).

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 get hashes for
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
Description
Type of visual hash to compute (default: both 'bmh1' and 'phash')

Response fields

Name
records
Type
array
Description
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 images/records that are matching (based on visual hashes).

!!! warning "Things to note" 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
Description
Type of visual hash to use for comparison (default: 'bmh1', optional: 'phash')
Name
range
Type
number
Description
Minimum threshold value for clustering (default: 0)

Response fields

Name
records
Type
array
Description
Array of records with merged duplicates
Name
records[].removed_records
Type
array
Description
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 image hash.

!!! warning "Things to note" The request contains records and query_record fields and returns query_records and answer_records. This is because we imitate the ranking endpoint of Photo and Product similarity service.

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
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 most matching)
Name
answer_distances
Type
array
Description
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
  }
}