Platform – Image Classification & Regression
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/
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 inrecords
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
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
}
]
}
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 tasksmulti_label
– for tagging tasksregression
– 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
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/
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
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/recognition/v2/task/__TASK_ID__/train/
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
curl -v -XGET \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/recognition/v2/task/
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
curl -v -XDELETE \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/recognition/v2/task/__TASK_ID__/
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 taskstag
– for tagging tasksvalue
– 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
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
-F 'name=New label' \
-F 'type=category' \
https://api.ximilar.com/recognition/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
# 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__"
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
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
-F 'label_id=__LABEL_ID__' \
https://api.ximilar.com/recognition/v2/task/__TASK_ID__/add-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
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 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
curl -v -XDELETE \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/recognition/v2/label/__LABEL_ID__/
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 to1024 (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
# 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"
}'
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
# 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__
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
# 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
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
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 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
curl -v -XDELETE \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/recognition/v2/training-image/__IMAGE_ID__/
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
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__"'