Skip to content

Image Recognition (previously

Ximilar Product Recognition service (previously provides a trainable image recognition API to recognize and classify images. It allows you to implement state-of-the-art artificial intelligence into your project. We provide a user interface for simple set up of your task, access to manage an account, upload images, train new models and evaluating result. After an easy setup, you get results over API and you are ready to build this functionality in your application. It’s easy, quick and highly scalable.


The task is where you start. Each task has a set of labels (categories, classes), training images and a recognition model. Only you can access your tasks and other data.

Model is the machine learning model behind your image recognition API. Its a neural network trained on your specific images and thus highly accurate at recognizing new images. Each model has an accuracy measured at the end of the training. Model is private only to its owner. Each retraining increases the version of the model by one and you can select a model version that is deployed.

Label (category) is a feature you want to recognize on your images. You must provide training images with this feature and Ximilar learns to recognize it.

Training of the model

Before training of the model, Ximilar Image Recognition service internally split your images into training images (80%) and testing images (20%). Training images are used for training, testing images are used to evaluate the accuracy of the model. The accuracy of the model is a number saying how accurately are your labels recognized. Accuracy 95% means 95 of 100 images will get the right label. Accuracy depends on the number of images uploaded for training and will not be very accurate for a low number of training images.

API reference

This is documentation of the Ximilar Image Recognition API. The API follows the general rules of Ximilar API as described in Section First steps.

Interactive API

You can find interactive API Reference after logging in at

The Image Recognition API is located at Each API entity (task, label, image) is defined by its ID. ID is formatted as a universally unique identifier (UUID) string. You can use IDs from browser URLs to quick access entities over programmatic access.


Classify endpoint - /v2/classify/

Classify endpoint executes an image recognition and it is the main endpoint of entire recognition system. It allows POST method and you can find it in our interactive API reference. You can pass an image in _url or _base64 fields. API endpoint /v2/classify gets JSON-formatted body where you need to specify records to process (up to 10), identification of task and version of your model(optional). You can also specify descriptor field to 1 and you are able to get visual descriptor of the image.

To sum up /v2/classify

  • can classify a batch of images (up to 10) at once
  • can extract visual features (descriptors) for similarity search
  • you can optionally specify a version of the model to be used
  • you cannot directly send a local image file (this is possible with /v1/classify), but you must first convert it to Base64


  • records: A list of real-life photos to find similar products; each record
    • must contain either of _url or _base64 field
  • task_id: UUID identification of your task.
  • version: Optional. Version of the model, default is the active/last version of your model.
  • descriptor: Optional, experimental. If set as "descriptor": 1 then result of record contains also vector (list of floats) of visual descriptor which you can use for similarity search.
curl -H "Content-Type: application/json" -H "authorization: Token __API_TOKEN__" -d '{"task_id": "0a8c8186-aee8-47c8-9eaf-348103xa214d", "version": 2, "descriptor": 0, "records": [ {"_url": "" } ] }'
import requests
import json
import base64

url = ''
headers = {
    'Authorization': "Token __API_TOKEN__",
    'Content-Type': 'application/json'
with open(__IMAGE_PATH__, "rb") as image_file:
    encoded_string = base64.b64encode('utf-8')

data = {
    'task_id': __TASK_ID__,
    'records': [ {'_url': __IMAGE_URL__ }, {"_base64": encoded_string } ]

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

The result has similar json structure:


  "task_id": "185x2019-1182-439c-900b-9f29c3w35926",
  "status": {
    "code": 200,
    "text": "OK"
  "statistics": {
    "processing time": 0.08802390098571777
  "descriptor": 0,
  "version": 9,
  "records": [
      "_status": {
        "code": 200,
        "text": "OK"
      "best_label": {
        "prob": 0.98351,
        "name": "dog",
        "id": "9d4b5433-add9-46e2-be64-7a928c5f68e8"
      "labels": [
          "prob": 0.98351,
          "name": "dog",
          "id": "9d4b5433-add9-46e2-be64-7a928c5f68e8"
          "prob": 0.01649,
          "name": "cat",
          "id": "08435c8c-554d-4a25-8702-f57526f1224f"
      "_url": "",
      "_width": 404,
      "_height": 564

Task endpoint - /v2/task/

Task endpoints let you manage tasks in your account. You can list all the tasks, create, delete, and modify created tasks. Until the first task training is successfully finished the production version of the task is -1 and the task cannot be used for classification.

List tasks (returns paginated result):

curl -v -XGET -H 'Authorization: Token __API_TOKEN__'

Create new categorization/classification/multi_class task (default, labels are exclusive):

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=My new task' -F 'description=Demo task'

Create new tagging/multi_label task (image can have one or more labels, for example image can contain 'cat', 'dog' and 'animal' labels if there are present on the picture):

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=My new task' -F 'type=multi_label' -F 'description=Demo task'

Delete task:

curl -v -XDELETE -H 'Authorization: Token __API_TOKEN__'

Label endpoint - /v2/label/

Label endpoints let you manage labels (categories) in your tasks. You manage your labels independently (list them, create, delete, and modify) and then you connect them to your tasks. Each task requires at least two labels for training. Each label must contain at least 20 images.

List all your labels (returns paginated result):

curl -v -XGET -H 'Authorization: Token __API_TOKEN__'

List all labels of the task:

curl -v -XGET -H 'Authorization: Token __API_TOKEN__'

Search all labels which contains substring:

curl -v -XGET -H 'Authorization: Token __API_TOKEN__'"__SEARCH_QUERY__"

Create new label:

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=New label'

Connect a created label to your task:

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'name=New label'

Training image endpoint - /v2/training-image/

Training image endpoint let you upload training images and add labels to these images. You can list training images, create, delete, modify created images. Because Ximilar Image Recognition will soon allow multi-label classification, the API allows to add more than one label to each training image.

Upload training image:

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'img_path=@__FILE__;type=image/jpeg'

Add label to a training image:

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__' -F 'label_id=__LABEL_ID__'

Get all images of given label (returns paginated result):

curl -v -XGET -H 'Authorization: Token __API_TOKEN__'

Training — /v2/task/TASK_ID/train/

Use training endpoint to start a model training. It takes few minutes up to few hours to train a model depending on the number of images in your training collection. You are notified about the start and the finish of the training by email.

Start training:

curl -v -XPOST -H 'Authorization: Token __API_TOKEN__'