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 imageimage
- image in the base64 formattext
- text query
Optional fields
num_similar
- an integer number of similar images to return. The default value is1
. The max value is50
.get_labels
- string, defining type of the metadata. Currently, onlycoco_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:
- 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