Similar Images API

This page will help you get started with Similar Images api.

To get URLs and similarity scores for similar images, you can use an API available at https://simage.info.

The request must be an HTTP POST, and its body must be a json with one of the fields:

Mandatory field

  • url - the URL of the image
  • image - image in the base64 format
  • text - text query

Optional fields

  • num_similar - an integer number of similar images to return. The default value is 1. The max value is 50.
  • get_labels - string, defining type of the metadata. Currently, only coco_yolov7 is supported.

You can have up to 100 requests per day. If you need more than 100 requests per day, you may register at https://ternaus.com/account and add money to your balance. After that first 100 requests per day will be free, and for the rest, you will be charged 1 cent per successful request.

Response

In case of success, the response mime-type is application/json and the response has the form of:

{
  "statusCode": 200,
  "body": '{"info": {"url": "https://ternaus.com"}, 
  "images": [{"url": <similar image URL>, 
                        "score": <similarity score>, 
                        "thumbnail_url": <URL to the downscaled and compressed to the webp format image>, 
                        "id": <image_id> }]}',
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "OPTIONS,POST"
  }
}

or 

{
  "statusCode": 200,
  "body": '{"info": {"url": "https://ternaus.com"}, 
                   "images": [{"url": <similar image URL>, 
                                         "score": <similarity score>, 
                                         "thumbnail_url": <URL to the downscaled and compressed to the webp format image>, 
                                         "id": <image_id> }],
                   "annotations": [{"image_id": <image_id>, 
                                                  "height": <height>, 
                                                  "width": <width>, 
                                                  "annotations": [{"name": <class name>, 
                                                                                  "score": <score>, 
                                                                                  "box": [<x_min>, <y_min>, <x_max>, <y_max>], 
                                                  "category_id": <category_id>}]}]
}',
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "OPTIONS,POST"
  }
}

if we request adding metadata.

Error

In case of an error:

the response mime-type is application/json, error type is indicated by the response status code, and details are in the json body, ie

{
  "statusCode": 403,
  "error": "Invalid API key",
  "headers": {
    "Access-Control-Allow-Origin": "*",
    "Access-Control-Allow-Methods": "OPTIONS,POST"
  }
}

Authentication

To generate X_API_KEY log in to https://ternaus.com/login and generate your token. You can find it later and regenerate if needed at https://ternaus.com/account.

Examples

We can perform a search from:

  1. URL
  2. Image
  3. text query
import json
import requests

headers = {
    "content-type": "application/json",
    "x-api-key": X_API_KEY,
}

API_URL = "https://simages.info"

# URL
def get_from_url(url: str, num_similar: int):
  body = {"url": url, "num_similar": num_similar}  
  return requests.post(API_URL, data=json.dumps(body), headers=headers)    

# Image
from image2base64.converters import rgb2base64

def get_from_image(image: Union[np.ndarray, PIL.Image.Image], num_similar: int):
  body = {"image": rgb2base64(image), "num_similar": num_similar}
  return requests.post(API_URL, data=json.dumps(body), headers=headers)
  
# Text
def get_from_text(text: str, num_similar: int):
    body = {"text": text, "num_similar": num_similar}
    return requests.post(API_URL, data=json.dumps(body), headers=headers)
  
### With metadata
# URL
def get_from_url(url: str, num_similar: int):
  body = {"url": url, "num_similar": num_similar, "get_labels": "coco_yolov7"}  
  return requests.post(API_URL, data=json.dumps(body), headers=headers)    

# Image
from image2base64.converters import rgb2base64

def get_from_image(image: Union[np.ndarray, PIL.Image.Image], num_similar: int):
  body = {"image": rgb2base64(image), "num_similar": num_similar, "get_labels": "coco_yolov7"}
  return requests.post(API_URL, data=json.dumps(body), headers=headers)
  
# Text
def get_from_text(text: str, num_similar: int):
    body = {"text": text, "num_similar": num_similar, "get_labels": "coco_yolov7"}
    return requests.post(API_URL, data=json.dumps(body), headers=headers)

// fetch from URL
const API_URL = "https://simages.info"

// From url
const body = {url: URL_TO_IMAGE, num_similar: NUM_SIMILAR}

// From text with metadata
const body = {text: TEXT_QUERY, num_similar: NUM_SIMILAR, get_labels: "coco_yolov7"}

// From image
const body = {image: IMAGE_IN_BASE64, num_similar: NUM_SIMILAR}

const response = await axios.post(API_URL, body, {
            headers: {
                "Content-Type": "application/json",
                "x-api-key": X_API_KEY,
            },
            timeout: 300 * 1000,
        });
        return JSON.parse(response.data.body);

Error codes

  • 200 - OK
  • 400 - Invalid request
  • 401 - Missing an API key
  • 402 - You exceeded free of charge day limit, contact us at https://www.ternaus.com/#contact to increase the limit.
  • 403 - Invalid API Key