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.

Screenshot

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.

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_id': "__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)