Platform – Object Detection
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: Object Detection.
The Object Detection service provides a trainable, custom detection API that identifies objects in your images and marks them with bounding boxes. It enables you to integrate state-of-the-art AI into your projects. We offer a user interface for easy task setup, account management, image uploads, model training, and result evaluation. Once configured in the App, you can get results via API and integrate them into your application.
If you're unsure how to train your object detection model, follow our step-by-step tutorial.
Training images for object detection models must be annotated by marking objects with bounding boxes or polygons. You can annotate via the API, the Ximilar App, or the dedicated interface Annotate.
All Endpoints
There are several useful API endpoints that you can use:
https://api.ximilar.com/detection/v2/task
https://api.ximilar.com/detection/v2/task/__TASK_ID__
https://api.ximilar.com/detection/v2/task/__TASK_ID__/add-label
https://api.ximilar.com/detection/v2/task/__TASK_ID__/remove-label
https://api.ximilar.com/detection/v2/task/__TASK_ID__/train/
Detect Objects
The detect
endpoint is the core of the object detection system.
It allows the POST method and accepts images via the _url
or _base64
fields.
Send a JSON-formatted request to /v2/detect, specifying:
- Up to 10 records (images to process)
- The task ID
- The model version (optional)
The response includes only detected objects with a predicted probability greater than 30%.
You can adjust this threshold using the keep_prob
parameter.
Required attributes
- Name
Authorization
- Type
- string
- Description
API token for authentication.
- Name
records
- Type
- array
- Description
A list of photos to detect objects; each record must contain either of
_url
or_base64
field.
- Name
task
- Type
- string
- Description
UUID identification of your task.
Optional attributes
- Name
version
- Type
- integer
- Description
Version of the model, default is the active/last version of your model.
- Name
keep_prob
- Type
- float
- Description
Specify value in (0.0-1.0). Default threshold probability is 30% (0.3).
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 detection results.
Request
curl -H "Content-Type: application/json" \
-H "authorization: Token __API_TOKEN__" \
https://api.ximilar.com/detection/v2/detect \
-d '{
"task_id": "0a8c8186-aee8-47c8-9eaf-348103xa214d",
"version": 2,
"descriptor": 0,
"records": [
{"_url": "https://bit.ly/2IymQJv"}
]
}'
Response
{
"task_id": "__TASK_ID__",
"records": [
{
"_url": "__SOME_URL__",
"_status": {
"code": 200,
"text": "OK"
},
"_width": 2736,
"_height": 3648,
"_objects": [
{
"name": "Person",
"id": "b9124bed-5192-47b8-beb7-3eca7026fe14",
"bound_box": [
2103,
467,
2694,
883
],
"prob": 0.9890862107276917
},
{
"name": "Car",
"id": "b9134c4d-5062-47b8-bcb7-3eca7226fa14",
"bound_box": [
100,
100,
500,
883
],
"prob": 0.9890862107276917
}
]
}
]
}
Create Task
Create a new object detection task.
Required attributes
- Name
Authorization
- Type
- string
- Description
Unique API token for authentication.
- Name
name
- Type
- string
- Description
Name of the new task.
Optional attributes
- Name
description
- Type
- string
- Description
Description of the new task.
Returns
HTTP error code 2XX, if the method was OK, and other HTTP error code, if the method failed. The response body is a JSON object containing the created task details.
Request
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
-F 'name=My new task' \
-F 'description=Demo task' \
https://api.ximilar.com/detection/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 Object Detection 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.
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
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/detection/v2/task/__TASK_ID__/train/
Create Object
Creates a bounding box (annotation) for a specific label on a training image, based on the coordinates you provide.
Required attributes
- Name
Authorization
- Type
- string
- Description
API token for authentication.
- Name
detection_label
- Type
- string
- Description
UUID of the detection label.
- Name
image
- Type
- string
- Description
UUID of the training image.
- Name
data
- Type
- array
- Description
Bounding box coordinates [xmin, ymin, xmax, ymax].
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 object details.
Request
curl -v -XPOST \
-H 'Authorization: Token __API_TOKEN__' \
-H 'Content-Type: application/json' \
--data '{
"detection_label": "__LABEL_ID__",
"image": "__IMAGE_ID__",
"data": [xmin, ymin, xmax, ymax]
}' \
https://api.ximilar.com/detection/v2/object
Get Objects of Image
Retrieve all objects (bounding boxes) linked to a specific image. These objects may have been created manually or via the API method for creating objects.
Required attributes
- Name
Authorization
- Type
- string
- Description
Unique API token for authentication.
- Name
image
- Type
- string
- Description
UUID of the training image.
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 array containing the objects associated with the image.
Request
curl -v -XGET \
-H 'Authorization: Token __API_TOKEN__' \
https://api.ximilar.com/detection/v2/object/?image=__IMAGE_ID__
Delete Object
Delete a specific object (bounding box) by its ID.
Deleting objects is permanent and cannot be undone.
Required attributes
- Name
Authorization
- Type
- string
- Description
API token for authentication.
- Name
object_id
- Type
- string
- Description
UUID of the object 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/detection/v2/object/__OBJECT_ID__/
Add Recognition Label to Object
Add a recognition label to a specific object (bounding box).
Required attributes
- Name
Authorization
- Type
- string
- Description
Unique API token for authentication.
- Name
object_id
- Type
- string
- Description
UUID of the object to add the label to.
- Name
label_id
- Type
- string
- Description
UUID of the recognition 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__' \
-H 'Content-Type: application/json' \
--data '{"label_id": "__LABEL_ID__"}' \
https://api.ximilar.com/detection/v2/object/__OBJECT_ID__/add-label
Remove Recognition Label from Object
Remove a recognition label from a specific object (bounding box).
Required attributes
- Name
Authorization
- Type
- string
- Description
Unique API token for authentication.
- Name
object_id
- Type
- string
- Description
UUID of the object to remove the label from.
- Name
label_id
- Type
- string
- Description
UUID of the recognition 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__' \
-H 'Content-Type: application/json' \
--data '{"label_id": "__LABEL_ID__"}' \
https://api.ximilar.com/detection/v2/object/__OBJECT_ID__/remove-label
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, tasks from a specific workspace as JSON response:
https://api.ximilar.com/recognition/v2/training-image/?workspace=WORKSPACE_ID
https://api.ximilar.com/detection/v2/label/?workspace=WORKSPACE_ID
https://api.ximilar.com/detection/v2/task/?workspace=WORKSPACE_ID
https://api.ximilar.com/detection/v2/object/?workspace=WORKSPACE_ID
Uploading/Creating object via POST to different workspace (requires workspace
field):
curl --location 'https://api.ximilar.com/detection/v2/object/' \
--header 'Authorization: Token __API_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
"detection_label": "__LABEL_ID__",
"image": "__IMAGE_ID__",
"data": [xmin, ymin, xmax, ymax],
"workspace": "WORKSPACE_ID"
}'