Platform - Image Classification & Regression

BasicsQuickstartXimilar PlatformVideo Tutorials

If you don't know how to train your image recognition model then read our step by step tutorial at our blog.

The Image Classification & Regression service provides custom image recognition API to train models & recognize, classify images or predict/regress continuous values from images. It allows you to implement state-of-the-art artificial intelligence into your project. We provide user interface for simple set up of your task (neural network definition), 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.

All endpoints

There are several useful API endpoints that you can use:

https://api.ximilar.com/recognition/v2/task
https://api.ximilar.com/recognition/v2/task/__TASK_ID__
https://api.ximilar.com/recognition/v2/task/__TASK_ID__/add-label
https://api.ximilar.com/recognition/v2/task/__TASK_ID__/remove-label
https://api.ximilar.com/recognition/v2/task/__TASK_ID__/train/
POST/v2/classify/

Classify Images

This endpoint executes a trained image recognition model on images for getting predictions. The endpoint allows POST method and you can pass an image in _url or _base64 fields.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    task
    Type
    string
    Description

    UUID identification of your task.

  • Name
    records
    Type
    array
    Description

    A list of real-life photos to find similar products; each record must contain either of _url or _base64 field.

Optional attributes

  • Name
    version
    Type
    integer
    Description

    Version of the model, default is the active/last version of your model.

  • Name
    store_images
    Type
    boolean
    Description

    If set to true then all images in the records are stored to your training images marked with a selected label. IDs of the stored images are returned in each of the record in field _stored_image_id. This feature must be turned on for specific task and is available only for users with Professional pricing plan.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object with the following fields:

  • Name
    task_id
    Type
    string
    Description

    ID of the task used for classification.

  • Name
    status
    Type
    object
    Description

    Status object containing code and text.

  • Name
    statistics
    Type
    object
    Description

    Object containing processing time statistics.

  • Name
    version
    Type
    integer
    Description

    Version of the model used.

  • Name
    records
    Type
    array
    Description

    Array of classification results for each input record.

Request

POST
/v2/classify/
curl -H "Content-Type: application/json" \
     -H "authorization: Token __API_TOKEN__" \
     https://api.ximilar.com/recognition/v2/classify \
     -d '{
       "task": "0a8c8186-aee8-47c8-9eaf-348103xa214d",
       "version": 2,
       "records": [
         {"_url": "https://bit.ly/2IymQJv"}
       ]
     }'

Response

{
  "task_id": "185x2019-1182-439c-900b-9f29c3w35926",
  "status": {
    "code": 200,
    "text": "OK"
  },
  "statistics": {
    "processing time": 0.08802390098571777
  },
  "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": "https://vize.ai/fashion_examples/10.jpg",
      "_width": 404,
      "_height": 564
    }
  ]
}
POST/v2/task/

Create Task

Create a new task for image classification, tagging, or regression.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    name
    Type
    string
    Description

    Name of the task.

  • Name
    type
    Type
    string
    Description

    Type of the task. Can be:

    • multi_class - For categorization tasks
    • multi_label - For tagging tasks
    • regression - For regression tasks

Optional attributes

  • Name
    description
    Type
    string
    Description

    Description of the task.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing the created task details.

Request

POST
/v2/task/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'name=My new task' \
     -F 'type=multi_class' \
     -F 'description=Demo task' \
     https://api.ximilar.com/recognition/v2/task/
POST/v2/task/{task_id}/train/

Train Task

Start training a model for the specified task. The training process may take from a few minutes to several hours depending on the number of images in your training collection. You will be notified about the start and finish of the training by email.

Before training of the model, Ximilar Custom 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, precision and recall 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.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    task_id
    Type
    string
    Description

    UUID of the task to train.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing the training status.

Request

POST
/v2/task/{task_id}/train/'
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/task/__TASK_ID__/train/
GET/v2/task/

List Tasks

List all tasks in your account. Returns paginated results.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing paginated list of tasks.

Request

GET
/v2/task/
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/task/
DELETE/v2/task/{task_id}/

Delete Task

Delete a specific task by its ID.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    task_id
    Type
    string
    Description

    UUID of the task to delete.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

DELETE
/v2/task/{task_id}/
curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/task/__TASK_ID__/
POST/v2/label/

Create Label

Create a new label (category, tag, or value) for your tasks.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    name
    Type
    string
    Description

    Name of the label.

  • Name
    type
    Type
    string
    Description

    Type of the label. Can be:

    • category - For categorization tasks
    • tag - For tagging tasks
    • value - For regression tasks

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing the created label details.

Request

POST
/v2/label/
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'name=New label' \
     -F 'type=category' \
     https://api.ximilar.com/recognition/v2/label/
GET/v2/label/

List Labels

List all labels in your account. Returns paginated results. You can filter labels by task or search by name.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

Optional attributes

  • Name
    task
    Type
    string
    Description

    Filter labels by task ID.

  • Name
    search
    Type
    string
    Description

    Search labels by name substring.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing paginated list of labels.

Request

GET
/v2/label/
# List all labels
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/label/

# List labels for specific task
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/label/?task=__TASK_ID__

# Search labels by name
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/label/?search="__SEARCH_QUERY__"
POST/v2/task/{task_id}/add-label

Add Label to Task

Connect a label to your task. The label type must match the task type (category for Categorization task, tag for Tagging task, value for Regression task).

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    task_id
    Type
    string
    Description

    UUID of the task.

  • Name
    label_id
    Type
    string
    Description

    UUID of the label to add.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

POST
/v2/task/{task_id}/add-label
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'label_id=__LABEL_ID__' \
     https://api.ximilar.com/recognition/v2/task/__TASK_ID__/add-label
POST/v2/task/{task_id}/remove-label

Remove Label from Task

Remove a label from your task. This only detaches the label from the task but doesn't delete the label itself.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    task_id
    Type
    string
    Description

    UUID of the task.

  • Name
    label_id
    Type
    string
    Description

    UUID of the label to remove.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

POST
/v2/task/{task_id}/remove-label
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'label_id=__LABEL_ID__' \
     https://api.ximilar.com/recognition/v2/task/__TASK_ID__/remove-label
DELETE/v2/label/{label_id}/

Delete Label

Delete a label from your account. This will also remove the label from all tasks it was connected to.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    label_id
    Type
    string
    Description

    UUID of the label to delete.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

DELETE
/v2/label/{label_id}/
curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/label/__LABEL_ID__/
POST/v2/training-image/

Upload Training Image

Upload training images to be used for model training. You can upload images via file, URL, or base64 encoding.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    img_path
    Type
    file
    Description

    Image file to upload (when using file upload).

  • Name
    base64
    Type
    string
    Description

    Base64 encoded image data (when using base64 upload).

Optional attributes

  • Name
    meta_data
    Type
    object
    Description

    Additional metadata for the image.

  • Name
    noresize
    Type
    boolean
    Description

    If set to true, the image will not be resized during upload.

  • Name
    workspace
    Type
    string
    Description

    ID of the workspace to upload the image to.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing the uploaded image details.

Request

POST
/v2/training-image/'
# File upload
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'img_path=@__FILE__;type=image/jpeg' \
     https://api.ximilar.com/recognition/v2/training-image/

# Base64 upload
curl --request POST \
     --url https://api.ximilar.com/recognition/v2/training-image/ \
     --header 'authorization: Token API_TOKEN' \
     --header 'content-type: application/json' \
     --data '{
       "meta_data": {"field": "key"},
       "noresize": false,
       "base64": "BASE64"
     }'
GET/v2/training-image/

List Training Images

List all training images in your account. Returns paginated results. You can filter images by label.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

Optional attributes

  • Name
    label
    Type
    string
    Description

    Filter images by label ID.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed. Body of the response is a JSON object containing paginated list of training images.

Request

GET
/v2/training-image/
# List all images
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/training-image/

# List images for specific label
curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/training-image/?label=__LABEL_ID__
POST/v2/training-image/{image_id}/add-label

Label Training Image

Add a label to a training image. For regression tasks, you can also specify a value.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    image_id
    Type
    string
    Description

    UUID of the training image.

  • Name
    label_id
    Type
    string
    Description

    UUID of the label to add.

Optional attributes

  • Name
    value
    Type
    number
    Description

    Value for regression label (only for regression tasks).

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

POST
/v2/training-image/{image_id}/add-label
# Add category/tag label
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'label_id=__LABEL_ID__' \
     https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/add-label

# Add regression label with value
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'label_id=__LABEL_ID__' \
     -F 'value=__VALUE__' \
     https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/add-label
POST/v2/training-image/{image_id}/remove-label

Remove Label from Training Image

Remove a label from a training image.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    image_id
    Type
    string
    Description

    UUID of the training image.

  • Name
    label_id
    Type
    string
    Description

    UUID of the label to remove.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

POST
/v2/training-image/{image_id}/remove-label
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'label_id=__LABEL_ID__' \
     https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/remove-label
DELETE/v2/training-image/{image_id}/

Delete Training Image

Delete a training image from your account.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    image_id
    Type
    string
    Description

    UUID of the training image to delete.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

DELETE
/v2/training-image/{image_id}/
curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/
POST/v2/training-image/{image_id}/update-value

Update Regression Label Value

Update the value of a regression label for a training image.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    API token for authentication.

  • Name
    image_id
    Type
    string
    Description

    UUID of the training image.

  • Name
    label_id
    Type
    string
    Description

    UUID of the regression label.

  • Name
    value
    Type
    number
    Description

    New value for the regression label.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

POST
/v2/training-image/{image_id}/update-value
curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'label_id=__LABEL_ID__' \
     -F 'value=__VALUE__' \
     https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/update-value

Using Different Workspace

When making an API request, the default workspace associated with the user's API token is used. To access data or upload images to a different workspace, you must explicitly specify the workspace—either in the URL (typically for GET requests) or in the JSON payload (typically for POST requests).

Examples

Getting all images, labels, tasks from specific workspace:

https://api.ximilar.com/recognition/v2/training-image/?workspace=WORKSPACE_ID
https://api.ximilar.com/recognition/v2/label/?workspace=WORKSPACE_ID
https://api.ximilar.com/recognition/v2/task/?workspace=WORKSPACE_ID

Uploading image via POST to different workspace (requires workspace field):

curl --location 'https://api.ximilar.com/recognition/v2/training-image/' \
--header 'Authorization: Token __API_TOKEN__' \
--header 'Content-Type: application/json' \
--data '
  {
    "meta_data": {
      "product_id": "24618"
    },
    "noresize": true,
    "base64": "UklGRiBuAABX..."
    "workspace": "WORKSPACE_ID"
  }
'

Adding label to the image (doesn't require the workspace specification):

curl --location 'https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/add-label' \
--header 'Authorization: Token __API_TOKEN__' \
--form 'label_id="__LABEL_ID__"'

Was this page helpful?