Skip to content

Custom Image Recognition (previously

Ximilar Custom Image 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, tags) and a recognition model. Each label can be assigned to multiple training images. 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.

The task can be Tagging ('multi_label') or Categorization ('multi_class') which you need to select during/when creating the task. Tagging task automatically creates one Negative Label.

Create Categorization task with Categories (Labels) when:

  • Categorization makes the assumption that each sample is assigned to one and only one label.
  • That means that Labels are mutually exclusive so Image within Recognition Task should (must) have only one Label/Category
  • Desired prediction output should have only one right Label/Category
  • You always know that when your task/model will be in production, only images with the domain of your labels will be sent. That means if you create task for distinguishing Apples from Bananas, you are not expectings images with Pineapples or Dogs.

Some examples of correct categorization tasks:

  • Recognizing fashion brands like Adidas, Nike, Rebook, Puma ... from Images of logos, and only one logo is present on the image
  • If you want to recognize Malign vs Benign Cells
  • If you want to recognize Cats Vs Dogs Vs Birds
  • If you want to recognize Cat Vs Not-A-Cat
  • If you want to recognize images with watermark or without
  • If you want to recognize Bedroom Vs Bathroom Vs Kitchen Vs Pool
  • If you want to recognize Damage Items vs Non-damaged item
  • If you want to categorize Color of Dress like Red vs Green vs Blue

Create Tagging task with Tags (Labels) when:

  • The labels are not mutually exclusive so Image within the task can have multiple tags (Labels).
  • That means multiple tags are relevant for the image and the tags are probably somehow related.
  • That means desired prediction output for the image can have multiple ground truth labels.

Some examples of correct tagging tasks:

  • If you want to build Tagger for Dresses with tags Red, Green, Blue, Maxi, Midi, Mini, Long Sleeves, Short Sleeves, No Sleeves, ...
  • If you want to assign features to Real Estate Images as Indoor, Outdoor, Kitchen, Wooden, Table, Chair, Modern, Fireplace, Hardwood Floor, TV, ...
  • If you want to recognize Cat Vs Not-A-Cat (this is possible also in Categorization, here your Not-A-Cat label is represented by negative label)

Be aware that you can create multiple Categorization tasks (one task for recognizing Colors another for Shape and another for Pattern) to simulate behavior of Tagging task.

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 (category):

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

Create new label (tag):

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

Connect a label to your task (category to Categorization task and tag to Tagging task):

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

Remove a label from your task:

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

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__'

Remove label from 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__'