Platform – 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.

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.

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.

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

Was this page helpful?