Playment: API Developer Docs

The Playment Developer Hub

Welcome to the Playment developer hub.
Here, You'll find comprehensive documentation & examples to help you start working with Playment as quickly as possible, and get support if you get stuck.

Get Started

API Reference

You can use Playment's APIs to access a pool of thousands of human workers to perform data labelling tasks

 

Introduction

Playment offers fully managed enterprise-friendly solutions for data labelling.
You just need to send us the raw data and we'll take care of everything else.

Check out the documentation below to see how easy it is to use the API.

You can check out these examples to see how other developers are utilising the Playment API.

Contact us at hello@playment.in to get started.

Authentication

 
  • Authentication: Authenticate your account by including your secret key in API requests. The secret x-client-key ensures that only you are able to access your projects. We expect the API key to be included in all API requests sent to our server.
  • Callback Auth: If you’d like to authenticate our callbacks, Playment can send a x-playment-key header with each callback. You will need to share the key with us via a secure channel.

Security

 
  • Network Security: To ensure network security, you can whitelist our IP addresses so that you accept callback requests originating only from our servers

Creating a request

 

A request represents one piece of work that you would want our workers to do for you.

Hit our Feedline API to create a request, or what we call, a feed line unit (FLU)

Create Feed Line Unit

POST https://staging-api.playment.in/v1/project/ project_id /feedline *
POST https://api.playment.in/v1/project/ project_id /feedline

Parameters

project_id : To be passed in the url
x-client-key : Secret key to be passed as a header

* We'll share the project_id and x-client-key separately with you via a secure channel

Payload

{  
   "reference_id":"001",
   "data":{  
      "image_url":[  
         "https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1",
         "https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+2",
         "https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+3"
      ]
   },
   "tag":"categorise_image"
}

Check out the examples below to see different types of request structures.

x-client-key

Each request requires authentication with an API-key (x-client-key) which we verify before accepting a request.

reference_id

reference_id is a unique identifier for a request. We'll fail a request if you've sent another request with the same reference_id previously. This helps us ensure that we don't charge you for work which we've already done for you.

tag

Each request should have a tag which tells us what operation needs to be performed on that request. We'll share this tag with you during the integration process.

QPS

The API currently supports up to 20 requests per second.

Error Codes

FS_0001

Duplicate Reference Id

FS_0002

Reference Id Missing

FS_0003

Invalid Data Passed

FS_0004

Data missing

FS_0005

Tag Missing

FS_0006

Feed Line Unit not found

FS_0007

Image urls not valid

GE_0001

Malformed JSON/Invalid UUID passed

GE_0002

Parameter missing

Sample requests & responses

With error cases

 
{
	"reference_id": "reference_1",
	"data": {
		"image_url": ["URL_1", "URL_2"],
		"image_secondary": "URL_3"
	},
	"tag": "image_qc"
}
 
{
	"data": {
		"image_url": ["URL_1", "URL_2"],
		"image_secondary": "URL_3"
	},
	"tag": "image_qc"
}
 
{
	"reference_id": "reference_1",
	"data": {
		"image_url": ["URL_1", "URL_2"],
	},
	"tag": "image_qc",
}
 
{
	"reference_id": "reference_1",
	"data": {
		"image_url": 1234,
	},
	"tag": "image_qc"
}
 
{
	"feed_line_unit": {
		"flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f80",
		"reference_id": "ref_id_1",
		"tag": "image_qc"
	},
	"success": true
}
 
{
  "error": {
    "code": "FS_0002",
    "message": "Reference Id Missing"
  },
  "success": false
}

{
  "error": {
    "code": "GE_0001",
    "message": "Malformed json"
  },
  "success": false
}
 
{
  "error": {
    "code": "FS_0003",
    "message": "Invalid data passed",
    "validations": [
      {
        "validation_code": "WRONG_DATA_TYPE",
        "meta_data": {
          "fields": [
            "image_url"
          ]
        }
      }
    ]
  },
  "success": false
}

Error codes

 
Error Code
Reason

FS_0001

Duplicate Reference Id

FS_0002

Reference Id Missing

FS_0004

Data missing

FS_0005

Tag Missing

FS_0006

Feed Line Unit not found

FS_0007

Image urls not valid

GE_0001

Malformed JSON/Invalid UUID passed

GE_0002

Parameter missing

Bounding Boxes

 

Bounding boxes for object detection in images

Note:

Note for existing customers: This will be Playment's new data structure. The old data structure will be deprecated and non-functional from September 1st, 2018.

{  
   "reference_id":"001",
   "data":{
     "image_url":"https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"
   },
   "tag":"draw_bounding_boxes"
}
 
{
    "feed_line_units": [{
   	 "reference_id": "001",
   	 "flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
   	 "status": "COMPLETED",
   	 "tag": "draw_bounding_boxes",
   	 "result": [
       {
         "label": "television",
         "coordinates": [
           {"x": 0.38, "y": 0.19}, 
           {"x": 0.57, "y": 0.19}, 
           {"x": 0.57, "y": 0.44}, 
           {"x": 0.38, "y": 0.44}]
       },
       {
         "label": "plant",
         "coordinates": [
           {"x": 0.38, "y": 0.19}, 
           {"x": 0.57, "y": 0.19}, 
           {"x": 0.57, "y": 0.44}, 
           {"x": 0.38, "y": 0.44}]
       }
       ...
     ]
    ]
}

LiDAR Annotations

 

An endpoint to annotate cuboids in LiDAR data and track them across frames

The coordinate system for the point cloud are described below:

  • positive x-axis : Red(in direction of the ego-car motion)
  • positive y-axis : Green(towards the left side of the ego-car)
  • positive z-axis : Blue(vertically upwards, follows the right-hand rule)

Notes:

{  
   "reference_id":"001",
   "data":{
     "frames": [
       {
         "imu": {
           "delX": 0,
           "delY": 0,
           "delZ": 0,
           "del_rotX": 0,  //value in radians 
           "del_rotY": 0,
           "del_rotZ": 0
         },
         "cameras": [
           {
             "camera_id": "0",
             "image_url": "https://s3.amazonaws.com/bucket/____.JPG"
           }
         ],
         "frame_id": 0,
         "point_cloud": "https://s3.amazonaws.com/bucket/____.PCD"
       },
       {}, 
       {}
     ],    
     "calibration": {
       "cameras": [
         {
           "id": 0,
           "rotation_matrix": [
             [r11, r12, r12, 0],
             [r21, r22, r23, 0],
             [r31, r32, r33, 0],
             [0,   0,   0,   1]
           ],
           "camera_origin_3D": [x0,y0,z0],  //camera-origin in 3D world
           "projection_matrix": [
             [fx, 0,  cx,  0],
             [0,  fy, cy,  0],
             [0,  0,  1,   0]
           ],
           "translation_matrix": [
             [1,  0,  0, -tx],
             [0,  1,  0, -ty],
             [0,  0,  1, -tz],
             [0,  0,  0,  1 ]
           ]
         }
       ],
       "point_cloud": [
         {
           "type": "pcd",
           "format": [
             {
               "key": "x",
               "datatype": "float32"
             },
             {
               "key": "y",
               "datatype": "float32"
             },
             {
               "key": "z",
               "datatype": "float32"
             },
             {
               "key": "intensity",
               "datatype": "float32"
             }
           ],
           "hardware": "lidar"
         }
       ]
     }
   },
   "tag":"lidar_track_cuboids"
}
 
{
  "feed_line_units": [
    {
      "reference_id": "001",
      "flu_id": "3bcbc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
      "status": "COMPLETED",
      "tag": "lidar_track_cuboids",
      "result": {
        "annotations": [
          {
            "tracking_id": "85164320-42cb-47b7-9f3d-de004d6a5aba",
            "type": "cuboid3d",
            "label": "Obstruction",
            "frames": [
              {
                "frame_id": "0",
                "annotation_id": "12345620-42cb-47b7-9f3d-de004d6a5aba",
                "center": {
                  "x": 34.915330335708234,
                  "y": -2.1073208887785713,
                  "z": -1.2032084902657283
                },
                "rotation": {
                  "x": 0,
                  "y": 0,
                  "z": 1
                },
                "dimensions": {
                  "width": 0.2260065451,
                  "height": 0.7935830195,
                  "length": 0.2046092338
                },
                "attributes": {
                  "Object State": {
                    "value": "Moving"
                  },
                  "Occlusion State": {
                    "value": "Not Occluded"
                  }
                }
              },
              {
                "frame_id": "1",
                "annotation_id": "2345620-42cb-47b7-9f3d-de004d6a5aba1",
                "center": {
                  "x": 34.915330335708234,
                  "y": -2.1073208887785713,
                  "z": -1.2032084902657283
                },
                "rotation": {
                  "x": 0,
                  "y": 0,
                  "z": 1.1
                },
                "dimensions": {
                  "width": 0.2260065451,
                  "height": 0.7935830195,
                  "length": 0.2046092338
                },
                "attributes": {
                  "Object State": {
                    "value": "Moving"
                  },
                  "Occlusion State": {
                    "value": "Not Occluded"
                  }
                }
              },
              {
                "frame_id": "2",
                "annotation_id": "345620-42cb-47b7-9f3d-de004d6a5aba12",
                "center": {
                  "x": 34.915330335708234,
                  "y": -2.1073208887785713,
                  "z": -1.2032084902657283
                },
                "rotation": {
                  "x": 0,
                  "y": 0,
                  "z": 1.2
                },
                "dimensions": {
                  "width": 0.2260065451,
                  "height": 0.7935830195,
                  "length": 0.2046092338
                },
                "attributes": {
                  "Object State": {
                    "value": "Moving"
                  },
                  "Occlusion State": {
                    "value": "Not Occluded"
                  }
                }
              }
            ]
          }
        ]
      }
    }
  ]
}

Bounding Box Validation

 

Validate the performance of your object detection models

{  
   "reference_id":"001",
   "data":{
     "image_url":"https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1",
     "boxes": [{
       	 "id" : "box_0001",
         "label": "car",
         "coordinates": [
           {"x": 0.38, "y": 0.19}, 
           {"x": 0.57, "y": 0.19}, 
           {"x": 0.57, "y": 0.44}, 
           {"x": 0.38, "y": 0.44}]
       },
       {
         "id" : "box_0002",
         "label": "van",
         "coordinates": [
           {"x": 0.38, "y": 0.19}, 
           {"x": 0.57, "y": 0.19}, 
           {"x": 0.57, "y": 0.44}, 
           {"x": 0.38, "y": 0.44}]
       }]
   },
   "tag":"validate_boxes"
}
 
{
  "feed_line_units": [
    {
      "reference_id": "001",
      "flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
      "status": "COMPLETED",
      "tag": "validate_boxes",
      "result": [
        {
          "id": "box_0001",
          "label": {
            "judgement": "valid",
            "value": "car"
          },
          "coordinates": {
            "judgement": "invalid",
            "value": [
              {"x": 0.38, "y": 0.19}, 
              {"x": 0.57, "y": 0.19}, 
              {"x": 0.57, "y": 0.44}, 
              {"x": 0.38, "y": 0.44}]
          }
        },
        {
          "id": "box_0002",
          "label": {
            "judgement": "invalid",
            "value": "truck"
          },
          "coordinates": {
            "judgement": "valid",
            "value": [
              {"x": 0.38, "y": 0.19}, 
              {"x": 0.57, "y": 0.19}, 
              {"x": 0.57, "y": 0.44}, 
              {"x": 0.38, "y": 0.44}]
          }
        }
      ]
    ]
  }
}

Cuboids

 

Label perspective cuboids with coordinates of 6 vertices for any object in a 2D image for camera based depth perception models

{  
   "reference_id":"002",
   "data":{
     "image_url":"https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"
   },
   "tag":"draw_cuboids"
}
 
{
	"feed_line_units": [{
		"reference_id": "002",
		"flu_id": "3bcbc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
		"status": "COMPLETED",
		"tag": "draw_cuboids",
		"result": {
			"cuboids": [{
				"points": {
					"p1": {"x": 0.17,"y": 0.58},
					"p2": {"x": 0.26,"y": 0.58},
					"p3": {"x": 0.26,"y": 0.49},
					"p4": {"x": 0.17,"y": 0.49},
					"p5": {"x": 0.24,"y": 0.51},
					"p6": {"x": 0.35,"y": 0.52},
					"p7": {"x": 0.35,"y": 0.36},
          "p8": {"x": 0.25,"y": 0.37}
				},
				"front": {
					"coordinates": ["p1","p2","p3","p4"] //clockwise
				},
				"side": {
					"coordinates": ["p2","p3","p5","p6"]
				},
				"back": {
					"coordinates": ["p7","p8","p5","p6"]
				},
				"label": "Car - Sedan",
        "faces_visible": ["right","back"]
			}...
			]
		}
	}]
}

Landmarks

 

Facial landmark annotations for facial feature understanding

Landmarks on Human Face

Landmarks on Human Face

{  
   "reference_id":"001",
   "data":{
     "image_url":"https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"
   },
   "tag":"draw_landmarks"
}
 
{
	"feed_line_units": [{
		"reference_id": "002",
		"flu_id": "3bcbc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
		"status": "COMPLETED",
		"tag": "draw_landmarks",
		"result": {
			"landmarks": [{
			"points": {
				"p1": { "x": 0.17, "y": 0.58, "label": 1 },
				"p2": { "x": 0.26, "y": 0.63, "label": 2 },
        "p3": { "x": 0.27, "y": 0.63, "label": 3 },
        "p4": { "x": 0.29, "y": 0.59, "label": 4 },
        "p5": { "x": 0.25, "y": 0.46, "label": 5 },
        "p6": { "x": 0.22, "y": 0.42, "label": 6 }
		},
			"label": "nose"
		}, {
			"points": {
        "p1": { "x": 0.17, "y": 0.58, "label": 7 },
        "p2": { "x": 0.26, "y": 0.63, "label": 8 },
        "p3": { "x": 0.27, "y": 0.63, "label": 9 },
        "p4": { "x": 0.29, "y": 0.59, "label": 10 },
        "p5": { "x": 0.25, "y": 0.46, "label": 11 },
        "p6": { "x": 0.22, "y": 0.42, "label": 12 }
		},
			"label": "left-ear"
		}...]
		}
	}]
}

Semantic Segmentation

 

Assign a label to each pixel in an image

Semantically Segmented Urban Scene

Semantically Segmented Urban Scene

{  
   "reference_id":"001",
   "data":{
     "image_url":"https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"
   },
   "tag":"semantic_segmentation"
}
 
{
  "feed_line_units": [
    {
      "reference_id": "001",
      "flu_id": "3bcbc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
      "status": "COMPLETED",
      "tag": "semantic_segmentation",
      "image_url": "https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1",
      "result": {
        "grayscale_mask": "https://example.playment.io/001_grayscale.png",
        "grayscale_label_map": {
          "car" : "1",
          "pedestrian" : "2"
        },
        "rgb_mask": "https://example.playment.io/001_rgb.png",
        "rgb_label_map": {
          "car" : "#001ADE",
          "pedestrian" : "#BDF032"
        }
      }
    }
  ]
}

Polygons

 

Annotate object instances with polygons instead of pixel segmentation

{  
   "reference_id":"001",
   "data":{
     "image_url":"https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"
   },
   "tag":"draw_polygons"
}
 
{
	"feed_line_units": [{
		"reference_id": "001",
		"flu_id": "3bcbc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
		"status": "COMPLETED",
		"tag": "draw_polygons",
		"result": {
			"polygons": [{
				"points": {
					"p1": {"x": 0.17,"y": 0.58},
					"p2": {"x": 0.26,"y": 0.63},
					"p3": {"x": 0.27,"y": 0.63},
					"p4": {"x": 0.29,"y": 0.59},
					"p5": {"x": 0.25,"y": 0.46},
					"p6": {"x": 0.22,"y": 0.42}...
				},
				"edges": {
					"e1": ["p1","p2"],
					"e2": ["p2","p3"],
					"e3": ["p3","p4"],
					"e4": ["p4","p5"],
					"e5": ["p5","p6"],
					"e6": ["p6","p7"],
					"e7": ["p8","p9"]...
				},
				"label": "Sofa"
			}...
                 ]
		}
	}]
}

Annotation Attributes

 

In addition to the basic shape annotations, we provide labelling of any attributes associated with the parent annotations

Check the feed_line_units[0].result.rectangles[0].attributes key in the callback body shown on the right

{
    "feed_line_units": [{
   	 "reference_id": "001",
   	 "flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
   	 "status": "COMPLETED",
   	 "tag": "draw_bounding_boxes",
   	 "result": {
       "rectangles": [
         {
           "label": "television",
           "coordinates": [
             {"x": 0.38, "y": 0.19}, 
             {"x": 0.57, "y": 0.19}, 
             {"x": 0.57, "y": 0.44}, 
             {"x": 0.38, "y": 0.44}],
           "attributes": {
             "occlusion": 0,
             "leading_vehicle": True
           }
         },
         {
           "label": "plant",
           "coordinates": [
             {"x": 0.38, "y": 0.19}, 
             {"x": 0.57, "y": 0.19}, 
             {"x": 0.57, "y": 0.44}, 
             {"x": 0.38, "y": 0.44}],
            "attributes": {
              "occlusion": 1,
              "leading_vehicle": False
            }
         }
       ]
      }
    }]
}

What we send

 

You will be required to configure a callback_url, where we will POST the results of your request once it is completed.

POST https://<some_custom_callback_url>

We send the response as a JSON body, which looks like this:

{
    "feed_line_units": [{
   	 "reference_id": "001",
   	 "flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
   	 "status": "COMPLETED",
   	 "tag": "cat_or_dog",
   	 "result": {
       "category" : "cat"
    }]
}

The result object is a JSON which can contain one or more key-value pairs, depending on your requirements. Check the examples to understand how it can be used in various scenarios.

In case the images shared in the Feedline API are invalid or unavailable, we will retry multiple times before responding asynchronously to the Callback API with "status": "FAILED"

{
  "feed_line_units": [
    {
      "reference_id": "001",
      "flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
      "status": "FAILED",
      "tag": "cat_or_dog",
      "error": {
        "code": "FS_0003",
        "message": "Invalid data passed",
        "meta_data": {
          "failures": [
            {
              "field": "product_image_url",
              "type": "INVALID_IMAGE_LINK"
            },
            {
              "field": "review_image_url",
              "type": "INVALID_IMAGE_LINK"
            }
          ]
        }
      }
    }
  ]
}

Parameters

content-type : application/json

reference_id

reference_id is a unique identifier for a request. We'll fail a request if you've sent another request with the same reference_id previously. This helps us ensure that we don't charge you for work which we've already done for you.

flu_id

This is the unique ID that we generate for every request

status

PENDING : The data is currently being processed
COMPLETED : All the data has been processed and is ready for consumption by client
FAILED : Data validation or file download failed

As of today, you will not receive a response which has a `FAILED' status

tag

Each request should have a tag which tells us what operation needs to be performed on that request. Don't worry, We'll share this tag with you during the integration process.

Authentication

For authentication of the callbacks, we can send a x-playment-key header with each callback. You will need to share the key with us via a secure channel. If you receive requests without the set header, then it is not from Playment's side.

Error codes

 

On a callback request, you should respond with 200 HttpStatusCode to be considered as a successful request. Any non-200 HttpStatusCode will be considered as unsuccessful. In case of following non-200 HttpStatusCodes, we retry upto 3 times in an interval of 30 seconds:

Error Code
Description

408

Request Timeout

500

Internal Server Error

501

Not Implemented

502

Bad Gateway

503

Service Unavailable

504

Gateway Timeout

505

HTTP Version Not Supported

511

Network Authentication Required