Skip to content

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.

Simple 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 only the Recognition (previously Vize.ai) , Generic Tagging, Fashion Tagging and Dominant Colors.

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

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. For example, method for getting information about your task from our recognition system, will return JSON data like this:

CLICK TO SHOW JSON RESULT

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

Examples

curl -H "Content-Type: application/json" -H "authorization: Token __API_TOKEN__" https://api.ximilar.com/your-endpoint -d '{"records": [ {"_url": "https://bit.ly/2IymQJv" }, {"_base64": "data:image/jpeg;base64,/9j/4A"} ] }'
import requests
import json
import base64

url = 'https://api.ximilar.com/your-endpoint'
headers = {
    'Authorization': "Token __API_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
#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': [ {'_url': __IMAGE_URL__ }, {"_base64": encoded_string } ]
}

response = requests.post(endpoint, headers=headers, data=json.dumps(data))
if response.raise_for_status():
    print(json.dumps(response.json(), indent=2))
else:
    print('Error posting API: ' + response.text)