Platform – Instance Segmentation

Basics Quickstart Ximilar Platform

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: Instance Segmentation.

The Instance Segmentation service provides a trainable, custom segmentation API that identifies objects in your images and outlines each of them with a precise polygon (in addition to a bounding box). 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.

Training images for instance segmentation models must be annotated by marking objects with polygons. You can annotate via the API, the Ximilar App, or the dedicated interface Annotate. Every label connected to a task needs at least 20 annotated images before the task can be trained.

All Endpoints

There are several useful API endpoints that you can use:

https://api.ximilar.com/segmentation/v2/task
https://api.ximilar.com/segmentation/v2/task/__TASK_ID__
https://api.ximilar.com/segmentation/v2/task/__TASK_ID__/add-label
https://api.ximilar.com/segmentation/v2/task/__TASK_ID__/remove-label
https://api.ximilar.com/segmentation/v2/task/__TASK_ID__/train/

POST/v2/segment/

Segment Objects

The segment endpoint is the core of the instance segmentation system. It allows the POST method and accepts images via the _url or _base64 fields. Send a JSON-formatted request to /v2/segment, 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. Every object contains a bound_box ([xmin, ymin, xmax, ymax] in pixels) and a polygon — a flat list of points [x1, y1, x2, y2, ...] in absolute pixels outlining the object.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
records
Type
array
Description
A list of photos to segment 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 segmentation results.

Request

POST

/v2/segment/

curl -H "Content-Type: application/json" \
     -H "authorization: Token __API_TOKEN__" \
     https://api.ximilar.com/segmentation/v2/segment \
     -d '{
       "task_id": "0a8c8186-aee8-47c8-9eaf-348103xa214d",
       "version": 2,
       "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,
          "polygon": [
            2103,
            467,
            2650,
            470,
            2694,
            883,
            2110,
            880
          ]
        }
      ]
    }
  ]
}

POST/v2/task/

Create Task

Create a new instance segmentation 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/segmentation/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.

Before training, the Ximilar Instance Segmentation service automatically splits your annotated images into training and testing sets. The training set is used to teach the model, while the testing set is used to evaluate its performance through the standard COCO metric mAP (mean average precision of the predicted masks).

Every label connected to the task must have at least 20 images with polygons, otherwise the training request is rejected. Keep in mind that model quality depends heavily on the size and quality of your training dataset.

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/segmentation/v2/task/__TASK_ID__/train/

POST/v2/polygon

Create Polygon

Creates a polygon (annotation) for a specific label on a training image, based on the points you provide. Points are a flat list [x1, y1, x2, y2, ...] in absolute pixels; the bounding box of the polygon is computed automatically.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
segmentation_label
Type
string
Description
UUID of the segmentation label.
Name
image
Type
string
Description
UUID of the training image.
Name
data
Type
array
Description
Polygon points [x1, y1, x2, y2, ...] in absolute pixels (at least 3 points).

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 polygon details.

Request

POST

/v2/polygon

curl -v -XPOST \
     -H 'Authorization: Token __API_TOKEN__' \
     -H 'Content-Type: application/json' \
     --data '{
       "segmentation_label": "__LABEL_ID__",
       "image": "__IMAGE_ID__",
       "data": [x1, y1, x2, y2, x3, y3]
     }' \
     https://api.ximilar.com/segmentation/v2/polygon

GET/v2/polygon/

Get Polygons of Image

Retrieve all polygons linked to a specific image. These polygons may have been created manually in the App or via the API method for creating polygons.

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 polygons associated with the image.

Request

GET

/v2/polygon/

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

DELETE/v2/polygon/{polygon_id}/

Delete Polygon

Delete a specific polygon by its ID.

Deleting polygons is permanent and cannot be undone.

Required attributes

Name
Authorization
Type
string
Description
API token for authentication.
Name
polygon_id
Type
string
Description
UUID of the polygon to delete.

Returns

HTTP error code 2XX, if the method was OK and other HTTP error code, if the method failed.

Request

DELETE

/v2/polygon/{polygon_id}/

curl -v -XDELETE \
     -H 'Authorization: Token __API_TOKEN__' \
     https://api.ximilar.com/segmentation/v2/polygon/__POLYGON_ID__/

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 labels, tasks or polygons from a specific workspace as JSON response:

https://api.ximilar.com/segmentation/v2/label/?workspace=WORKSPACE_ID
https://api.ximilar.com/segmentation/v2/task/?workspace=WORKSPACE_ID
https://api.ximilar.com/segmentation/v2/polygon/?workspace=WORKSPACE_ID

Uploading/Creating polygon via POST to different workspace (requires workspace field):

curl --location 'https://api.ximilar.com/segmentation/v2/polygon/' \
--header 'Authorization: Token __API_TOKEN__' \
--header 'Content-Type: application/json' \
--data '{
  "segmentation_label": "__LABEL_ID__",
  "image": "__IMAGE_ID__",
  "data": [x1, y1, x2, y2, x3, y3],
  "workspace": "WORKSPACE_ID"
}'