Playment API
Integrate Playment's API with your workflow to leverage the intelligence of thousands of humans whenever you want
Get Started
You just need to send us the data. We 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.
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/v0/project/ project_id /feedline *
POST https://api.playment.in/v0/project/ project_id /feedline
Parameters
project_id : To be passed in the pathx-client-key : Secret key to be passed as a header
* We'll share the project_id and x-client_key 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 support upto 5 requests per second.
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
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
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.
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 processedCOMPLETED : All the data has been processed and is ready for consumption by client
As of today, you will not receive a response which does not have a `COMPLETED' 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.
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:
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
Security
- Authentication: The secret ‘x-client-key’ for each of our clients ensures that only you are able to access your projects
- To ensure network security, you can whitelist our IP addresses so that you accept callback requests originating only from our servers.
- Image urls on the app can be encrypted and signed so that they are accessible only from the client's device.
- HMAC encryption support
Computer Vision Training
{
"reference_id":"001",
"data":{
"instruction" : "Draw a box around the eagle",
"image_url":["https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"],
"result_structure" : {
"top-left" : "STRING",
"top-right" : "STRING",
"bottom-right" : "STRING",
"bottom-left" : "STRING"
}
},
"tag":"add_boxes"
}{
"feed_line_units": [{
"reference_id": "001",
"flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
"status": "COMPLETED",
"tag": "add_boxes",
"result": {
"top-left" : "(0.45,0.06)",
"top-right" : "(0.71,0.06)",
"bottom-right" : "(0.71,0.44)",
"bottom-left" : "(0.45,0.44)"
}]
}
Cataloging
{
"reference_id":"002",
"data":{
"instruction" : "Select the type of the bag",
"image_url":["https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"],
"result_structure" : {
"type" : "STRING"
}
},
"tag":"bag_type"
}{
"feed_line_units": [{
"reference_id": "002",
"flu_id": "3bcbc3fe-9fbc-4d7c-b951-a1d1bfb6f840",
"status": "COMPLETED",
"tag": "bag_type",
"result": {
"type" : "Handbags"
}]
}Text Classification
{
"reference_id":"003",
"data":{
"instruction" : "Classify the review",
"review_body":"Mobile is not booting up. It's getting heated while charging. I'm very disappointed that a new product has been delivered in such a bad condition",
"result_structure" : {
"class" : "STRING"
}
},
"tag":"classify_the_review"
}{
"feed_line_units": [{
"reference_id": "003",
"flu_id": "33abc3fe-9fbc-aa7c-b951-a1d1bfb6f840",
"status": "COMPLETED",
"tag": "classify_the_review",
"result": {
"class" : "Approve Review"
}]
}Transcription
{
"reference_id":"004",
"data":{
"instruction" : "Input the sales tax",
"image_url":["https://dummyimage.com/600x400/000/fff.jpg&text=Dummy+Image+1"],
"result_structure" : {
"sales_tax_amount" : "STRING"
}
},
"tag":"sales_tax_transcription"
}{
"feed_line_units": [{
"reference_id": "004",
"flu_id": "33abc3fe-9fbc-4d7c-b951-a1d1bfb6f812",
"status": "COMPLETED",
"tag": "sales_tax_transcription",
"result": {
"sales_tax_amount" : "1.49"
}]
}