Platform - Object Detection

Basics Quickstart Ximilar Platform Video Tutorials

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

The Object Detection service provides a trainable custom detection API to detect objects (bounding boxes) on the image. It allows you to implement state-of-the-art artificial intelligence into your project. We provide a user interface for simple set up of your task, 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. It's easy, quick and highly scalable.

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

Detect endpoint executes an image detection and it is the main endpoint of entire detection system. It allows POST method and you can pass an image in _url or _base64 fields. API endpoint /v2/detect gets JSON-formatted body where you need to specify records to process (up to 10), identification of task and version of your model(optional). The detect API endpoint returns only objects with predicted probability larger than 30 % (see keep_prob param).

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
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.
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 task for object detection.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
name
Type
string
Description
Name of the task.

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 '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 email.

Before training of the model, Ximilar Custom Object Detection 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/detection/v2/task/__TASK_ID__/train/

POST/v2/object

Create Object

Create a bounding box annotation (object) of a specific label type on an image.

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

Get all objects (bounding boxes) associated with a specific image.

Required attributes

Name
Authorization
Type
string
Description
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.

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

Getting all images, labels, tasks from specific workspace:

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