Platform – Object Detection

Basics Quickstart Ximilar Platform Video 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: 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/

POST/v2/detect/

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

POST

/v2/detect/

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
        }
      ]
    }
  ]
}

POST/v2/task/

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

POST

/v2/task/

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -F 'name=My new task' \
     -F 'description=Demo task' \
     https://api.ximilar.com/detection/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 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

POST

/v2/task/{task_id}/train/'

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/detection/v2/task/__TASK_ID__/train/

POST/v2/object

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

POST

/v2/object

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/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

GET

/v2/object/

curl -v -XGET \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/detection/v2/object/?image=__IMAGE_ID__

DELETE/v2/object/{object_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

DELETE

/v2/object/{object_id}/

curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/detection/v2/object/__OBJECT_ID__/

POST/v2/object/{object_id}/add-label

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

POST

/v2/object/{object_id}/add-label

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

POST/v2/object/{object_id}/remove-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

POST

/v2/object/{object_id}/remove-label

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"
}'