First Steps, Auth & Image Data
Ximilar provides several services for computer vision, machine learning and similarity search. Each of the service has similar workflow when dealing with the API.
Before using Ximilar API, you need to sign up/register at Ximilar app. After activating your account via email, you can obtain your API key from the user settings page. With this API key, you can authorize all your requests to our API.
Python library
If you are using Python in your project and do not want to play with requests, you can query our API with our library. Our library is on gitlab: https://gitlab.com/ximilar-public/ximilar-vize-api
At this point, this library covers Recognition (previously Vize.ai) , Generic Tagging, Fashion Tagging and Dominant Colors services.
Authentication & Authorization
User authentication and authorization is done through a API key (token) in the header of each HTTP request. You can find your token in user options. Here is a sample of authorization token in the header:
Authorization: Token 1af538baa90-----XXX-----baf83ff24
This authorization token is required in all HTTP methods as GET, POST, PUT, DELETE. When making request to our API, do not forget to include also Content-Type: application/json header. For example the POST request should look similar to:
POST /your-endpoint HTTP/1.1
Host: api.ximilar.com
Content-Type: application/json
Authorization: Token 1af538baa90-----XXX-----baf83ff24
Be aware that your Authorization header should include "Token " string prefix with your token, so "Token _YOUR_API_TOKEN".
Examples
curl -v -XGET -H "Content-Type: application/json" -H 'Authorization: Token __API_TOKEN__' https://api.ximilar.com/your-endpoint
import requests
url = 'https://api.ximilar.com/your-endpoint'
headers={'Authorization': "Token __API_TOKEN__",
'Content-Type': 'application/json'}
response = requests.get(url, headers=headers)
if response.raise_for_status():
print(response.text)
else:
print('Error posting API: ' + response.text)
JSON format and image data
Our API is based on REST API. This means that you can query our API with HTTP requests. Most of the API methods require a body in JSON format and all of the methods return data in JSON format.
All API methods that work with image data can contain either a URL (_url) to download the image from or a the actual binary image data encoded as Base64 (_base64). Typically, the images are passed within JSON field records or query_record (similarity search services) or query_records (similarity search services) which contains a JSON array with the image records.
BASE64 is in BGR order
If you use Base64, you can either directly encode the compressed image file (PNG, JPEG, WebP) or you can send the "uncompressed" pixel data. If you do, convert image first to BGR order of channels and then to base64 format.
CLICK TO SHOW JSON REQUEST DATA
{
"records": [
{ "_id": "2342", // (note that it's a string)
"_url": "https://example.com/my_image.jpg",
"product_id": "unique product string",
"my_category": "customer category",
"product_price": 32.5,
"my_tags": [ "one", "two", "three" ]
}
]
}
For example, method for getting labels/tags from recognition task system, will return JSON data like this:
CLICK TO SHOW EXAMPLE OF JSON RESULT (RECOGNITION)
{
"records": [
{
"_url": "__SOME_URL__",
"_status": {
"code": 200,
"text": "OK",
"request_id": "__SOME_ID__"
},
"_id": "__SOME_ID__",
"_width": 415,
"_height": 1024,
"labels": [
{
"prob": 0.79654,
"name": "__SOME_BEST_LABEL__",
"id": "__SOME_ID__"
},
{
"prob": 0.08047,
"name": "__SOME_LABEL__",
"id": "__SOME_ID__"
},
{
"prob": 0.07731,
"name": "__SOME_LABEL__",
"id": "__SOME_ID__"
},
{
"prob": 0.02297,
"name": "__SOME_LABEL__",
"id": "__SOME_ID__"
},
{
"prob": 0.02271,
"name": "__SOME_LABEL__",
"id": "__SOME_ID__"
}
],
"best_label": {
"prob": 0.79654,
"name": "__SOME_BEST_LABEL__",
"id": "__SOME_ID__"
}
}
],
"status": {
"code": 200,
"text": "OK",
"request_id": "__SOME_ID__",
"proc_id": "__SOME_ID__"
},
"statistics": {
"processing time": 0.9965865612030029
}
}
CLICK TO SHOW EXAMPLE OF JSON RESULT (SEARCH)
{
"status" : {
"code" : 200,
"text" : "OK"
},
"statistics" : {
"OperationTime" : 1
},
"answer_records":[
{
"_id" : "__SOME_ID__",
"_url": "__SOME_URL__",
"category": "__SOME_CATEGORY__"
},
{
"_id" : "__SOME_ID__",
"_url": "__SOME_URL__",
"category": "__SOME_CATEGORY__"
},
{
"_id" : "__SOME_ID__",
"_url": "__SOME_URL__",
"category": "__SOME_CATEGORY__"
}
],
"answer_distances" : [ 40.0, 50.0, 60.0 ],
"answer_count" : 3
}
Examples
To query API you can use any programming language or any software as Curl, Insomnia. We are providing also python client library.
curl -H "Content-Type: application/json" -H "authorization: Token __API_TOKEN__" https://api.ximilar.com/your-endpoint -d '{"records": [ {"_url": "__SOME_URL__" }, {"_base64": "data:image/jpeg;base64,/9j/4A...."} ] }'
import requests
import json
import base64
endpoint = 'https://api.ximilar.com/your-endpoint'
headers = {
'Authorization': "Token __TOKEN__",
'Content-Type': 'application/json'
}
# First way to load base64
with open(__IMAGE_PATH__, "rb") as image_file:
encoded_string = base64.b64encode(image_file.read()).decode('utf-8')
# Second way to load base64 data with opencv
# import cv2
#image = cv2.imread(__IMAGE_PATH__) # this will return image in BGR
#retval, buffer = cv2.imencode('.jpg', image)
#encoded_string = base64.b64encode(buffer).decode('utf-8')
data = {
'records': [{"_base64": encoded_string}, {"_url": __URL_PATH__}],
'task': "__TASK_ID__"
}
response = requests.post(endpoint, headers=headers, data=json.dumps(data))
print(json.dumps(response.json(), indent=2))
# pip install ximilar-client
from ximilar.client import RestClient
client = RestClient(token="__TOKEN__")
result = client.custom_endpoint_processing([{"_file": "__FILE_PATH__"}])
print(result)
Supported Image Formats
Right now you can send images to the api (in fields of _base64 or _url) with these supported formats:
JPG, JPEG, PNG, WEBP, HEIC, BMP, TIFF, JFIF
Formats with limited support:
GIF (we load only first frame)
We are not supporting:
GIF, AVIF, JP2, PSD, SVG, HEIF, PDF