Platform – Image Classification & Regression

BasicsQuickstartXimilar PlatformVideo Tutorials

To access the Ximilar Computer Vision Platform, first register at Ximilar App to get your API token. Actions listed on this page can also be done via Ximilar App: Image Classification.

The Image Classification by Ximilar enables you to train custom image recognition models for categorization, tagging and value regression and deploy them via API. It is an easy way to semalessly implement visual artificial intelligence into your own app or system.

Ximilar App serves as an interface for simple set up of your image classification tasks (neural network definition), as well as the management of your account, image uploading, ML model training, and evaluation of results. After the initial setup, you can access all services via API and integrate them in your own system.

To learn how to train your image recognition model, check out our guides How to Train a Custom Image Classifier in 5 Minutes and How to Build Your Own Image Recognition API?.

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 runs a trained image recognition model to generate predictions for submitted images. Use the POST method and provide the image via the _url or _base64 field.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    task
    Type
    string
    Description

    UUID identification of your task.

  • Name
    records
    Type
    array
    Description

    A list of photos to classify; each record must contain either _url or _base64 field.

Optional attributes

  • Name
    version
    Type
    integer
    Description

    Version of the model. By default, the last version of your model is active (used).

  • Name
    store_images
    Type
    boolean
    Description

    If set to true, all images in records are saved as training images with a selected label.
    The ID of each stored image is returned in the _stored_image_id field of each record.
    This feature must be enabled (contact us to enable it) for the specific task and is available only in the Professional plan.
    It allows you to store labeled images in your workspace for future use (e.g., training or data collection).

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 value regression. You will need to select appropriate task type based on your use case – see Overview for more details.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique API token for authentication.

  • Name
    name
    Type
    string
    Description

    Name of the new task.

  • Name
    type
    Type
    string
    Description

    Type of the task. Can be one of the following:

    • multi_class – for categorization tasks
    • multi_label – for tagging tasks
    • regression – for value 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 e-mail.

Before training, the Ximilar Custom Image Recognition service automatically splits your training images dataset: into training images (80%) and testing images (20%). The training set is used to teach the model, while the testing set is used to evaluate its performance through metrics such as accuracy, precision, and recall.

Accuracy indicates how well the model predicts the correct labels. For example, an accuracy of 95% means that 95 out of 100 images are correctly labeled.

Keep in mind that accuracy depends heavily on the size and quality of your training dataset; results may be unreliable with too few training images. Minimum number of training images is 20, but you should use at least 100–200 images per label for better results.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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 default workspace. Returns paginated results.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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.

Deleting tasks is permanent and cannot be undone.

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

    Unique API token for authentication.

  • Name
    name
    Type
    string
    Description

    Name of the label.

  • Name
    type
    Type
    string
    Description

    Type of the label. Can be one of the following:

    • 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

Lists all labels in your account. Returns paginated results. You can filter and search labels by task names.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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 a categorization task, tag for a tagging task, and value for a regression task.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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.

Deleting labels is permanent and cannot be undone.

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. By default, the image will be resized to 1024 (larger size) x Y pixels, preserving the aspect ratio.

  • 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

Lists all training images in your account. Returns paginated results. You can filter images by labels.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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

    Unique 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. This only detaches the label from the image but doesn't delete the label itself.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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

    Unique 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

If an image already has an assigned regression label with a value, you can use this endpoint to update that value.

Required attributes

  • Name
    Authorization
    Type
    string
    Description

    Unique 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

If you want to get all images, labels, and tasks from a specific workspace as JSON response:

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 an image via POST to a different workspace (requires the 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 a label to an image that already exists in your workspace (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?