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:

At this point, this library covers Recognition (previously , 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
Content-Type: application/json
Authorization: Token 1af538baa90-----XXX-----baf83ff24


curl -v -XGET -H "Content-Type: application/json" -H 'Authorization: Token __API_TOKEN__'
import requests

url = ''
headers={'Authorization': "Token __API_TOKEN__",
         'Content-Type': 'application/json'}
response = requests.get(url, headers=headers)
if response.raise_for_status():
    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. For example, method for getting information about your task from our recognition system, will return JSON data like this:


   "id": "31424-20412420-2141240-241",
   "name": "Cats and Dogs Classifier",
   "labels": [
            "id": "34124-2412412-21421",
            "name": "Cat"
            "id": "dfsds232fasfasfsfsf",
            "name": "Dog"

All API methods that work with image data can get either a URL to download the image from or a the actual binary image data encoded as Base64. Typically, the images are passed within JSON field records which contains a JSON array with the image records; each record must contain either field _url or _base64.

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.


curl -H "Content-Type: application/json" -H "authorization: Token __API_TOKEN__" -d '{"records": [ {"_url": "__SOME_URL__" }, {"_base64": "data:image/jpeg;base64,/9j/4A...."} ] }'
import requests
import json
import base64

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('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_id': "__TASK_ID__"

response =, 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__"}])