Overview

Built on our image similarity model, Custom Search is a robust tool to search your own image data for visual matches to a query image. The Custom Search API allows you to build and maintain an individualized database of images and submit images for model-based comparisons to this reference set. Following a query task, the API will return a list of any reference images classified as visual matches to the query image.

The flexibility to maintain a hand-picked reference database enables a wide variety of use-cases for Custom Search – from identifying fake profile photos on a social platform or scam listings on marketplaces to copy detection and spam control in content moderation applications.

Visual Similarity Model

Custom Search will capture both duplicates and modified versions. This includes manual image manipulations like rotations and text overlay, as well as more subtle augmentations such as introduction of noise, filters, and other pixel-level changes that may change the image hash but are visually imperceptible to humans.

Hive's visual similarity model will generate a similarity score – normalized between 0 and 1 – between a query image and any matches. A similarity score of 1.0 indicates an exact match between two images, while lower values indicate that the query image has been modified to some extent.

Custom Index Search API

The Custom Index Search API has three different endpoints:

"Add" Endpoint: used to add images to your reference index
"Query" Endpoint: used to search your reference library for visual matches to an input image
"Remove" Endpoint: used to remove images from your reference index that you no longer wish to compare against

NOTE: The API Key used to authenticate each type of request will be the same for all three endpoints. Use the API Key associated with the "Add" Endpoint.

Adding an Image to your Index

Submitting a POST request to the "Add" endpoint will add the specified image to your custom index to be checked against in future searches. The request must include a public URL for the image's hosting location or specify a file path for a direct image upload.

For direct uploads, supported file formats include: .png, .jpg, and .webp

📘
ADD ENDPOINT
Synchronous: POST to https://api.thehive.ai/api/v2/custom_index/add/sync
Asynchronous: POST to https://api.thehive.ai/api/v2/custom_index/add/async

You can also choose to append descriptive metadata to be stored alongside the image. This could be an ID for the image, tags, source information, or anything else that would be useful to receive back in a query response.

For syntax and more information on submitting requests to Hive APIs, please see our API reference materials. Here, you'll also find a more detailed explanation of synchronous versus asynchronous submission.

Hive will then assign a unique identifier to the image, hash the image, and store the image alongside any metadata included in the "Add" request (tags, descriptors, your own ID, etc.).

Example API response objects for the "Add" endpoint are available here.

Querying your Index for an Input Image

Submitting a GET request to the query index enables you to access model-based comparisons between a query image and each image stored in your custom index. Again, the "Query" request must include a public URL to the query image or a file path for a direct media upload.

📘
QUERY ENDPOINT
Synchronous: GET to https://api.thehive.ai/api/v2/custom_index/query/sync
Asynchronous: GET to https://api.thehive.ai/api/v2/custom_index/query/async

When a task is submitted to the "Query" endpoint, our models will analyze the input image and search for visual matches to each image in your custom reference index.

The Custom Search API will then return a JSON object with links to any matching image assets, a similarity score for each match, and any descriptive metadata associated with the matching images.

NOTE: Querying an image willnot automatically add it to the index. You must add the image manually using the "Add" Endpoint.

Response Fields

In the response object, task.status.output will include a list of metadata on any images in your reference index that visually match the query image. Each image identified in the "matches" subfield will be described by the following response data:

task_id : a unique identifier generated and returned for the matching image when it was added to the index
score : similarity metric between the query image and the matching reference image computed by Hive models. Float value between 0 and 1. 1.0 indicates an exact match between the two images, while lower values indicate that the query image has been modified to some extent.
metadata : any metadata that was included with the matching image in an "Add" request

Removing an Image from your Index

If you no longer need to query against a particular reference image/video in your index, you can remove it with a DELETE request to the "Remove" endpoint. When calling this endpoint, you'll need to provide the task_id (returned when the file was initially added) of the file you want to remove.

📘
REMOVE ENDPOINT
Synchronous: DELETE to https://api.thehive.ai/api/v2/custom_index/remove/sync
Asynchronous: DELETE to https://api.thehive.ai/api/v2/custom_index/remove/async

An example API response object for successful "Remove" tasks is available here.

ℹ️
Moderation Dashboard - Custom Index
To use Custom Index Search with the Moderation Dashboard, refer to the Moderation Dashboard API Reference here