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

{
  "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:

URL
Image
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