Create a job

A JOB

POST https://api.playment.io/v1/projects/:project_id/jobs

This endpoint allows you to create a job

Path Parameters

Name	Type	Description
project_id	string	ID of the project in which you want to create the job

Headers

Name	Type	Description
x-api-key	string	API key for authentication

Request Body

Name	Type	Description
batch_id	string	A batch is a way to organize multiple jobs under one batch_id. You can create new batches from the dashboard or by using the batch creation API. If batch_id is left empty or the key is not present, the job is created in the Default batch in your project.
work_flow_id	string	The ID of the workflow inside which you want to create the job
data	object	The data object contains all the information and attachments required to label a job. The data object is defined below
reference_id	string	The unique identifier of the job

200

{
  "data": {
    "job_id": "3f3e8675-ca69-46d7-aa34-96f90fcbb732",
    "reference_id": "001",
    "work_flow_id": "2aae1234-acac-1234-eeff-12a22a237bbc"
  },
  "success": true
}

Payload

{
  "reference_id": "001",
  "data": {
    "image_url": "https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+1",
    "reference_data": {
      "vector": {
        "images": [
          {
            "image_url": "https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+1",
            "label": "camera 1"
          },
          {
            "image_url": "https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+1",
            "label": "camera 2"
          }
        ]
      }
    }
  },
  "work_flow_id": "2aae1234-acac-1234-eeff-12a22a237bbc"
}

Payload Definition

Key	Type	Description
data.reference_data	Object	The reference_data object contains an additional list of images that can be used as a reference while annotating the primary image. This is an optional key based on your requirement. data.reference_data.vector.images is an array of reference images where each object has 2 keys : image_url - URL of the image. label- Name of the image.
data.image_url	string	URL of the image.

Code Example

Python

import requests
import json

"""
Details for creating JOBS,
project_id  ->> ID of project in which the job will be created
x_api_key   ->> API key for authentication 
workflow_id ->> The workflow in which the job will be created
batch_id    ->> The batch in which job will be created
"""

# Additional helper function to create a batch
def create_batch(BATCH_NAME):
    base_url = f"https://api.playment.io/v1/projects/{PROJECT_ID}/batch"
    DATA = {"name":BATCH_NAME}
    response = requests.post(base_url, headers={'x-api-key': CLIENT_KEY}, json=DATA)
    response_data = response.json()
    if response.status_code >= 500:
        raise Exception(f"Something went wrong at Playment's end {response.status_code}")
    if 400 <= response.status_code < 500:
        raise Exception(f"{response_data['error']['message']} {response.status_code}")
    print(response_data)
    return response_data
    
#method that can be used to call the job creation api
def create_job(project_id, data, x_api_key):
    base_url = "https://api.playment.io/v1/projects/{}/jobs".format(project_id)
    headers = {'x-api-key': x_api_key}
    response = requests.post(base_url, headers=headers, json=data)
    
    print(response.json())
    if response.status_code >= 500:
        raise Exception(response.text)
    if 400 <= response.status_code < 500:
        raise Exception(response.text)
    return response.json()

if __name__ == "__main__":
    #list of frames in a single job
    image_url = "https://example.com/image_url_1"
    ref_image_url1 = "https://example.com/ref_image_url_1"
    ref_image_url2 = "https://example.com/ref_image_url_2"
    
    #reference_id should be unique for each job
    reference_id= "job1"

    project_id = ''
    x_api_key = ''
    workflow_id = ''
    batch_id = ''
    
    
    job_data = {
        'reference_id':reference_id,
        'work_flow_id':workflow_id,
        'data':{
            'image_url':image_url,
            'reference_data': {
                  'vector': {
                    'images': [
                      {
                        'image_url': ref_image_url1,
                        'label': 'camera 1'
                      },
                      {
                        'image_url': ref_image_url2,
                        'label': 'camera 2'
                      }
                    ]
                  }
                }
            },
        'batch_id': batch_id
    }
    
    response = create_job(project_id=project_id, data=job_data, x_api_key= x_api_key)
    print(response)
    

Creating jobs with pre-labeled data

If you have data which has been labeled previously by an ML model or by human labelers, you can create jobs with such labels already created. To do this, you need to send the annotation data in the data.maker_response key in the payload. The annotation data needs to be in our annotation format.

Here's an example

{  
   "reference_id":"001",
   "data":{
     "image_url":"https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+1",
     "maker_response" : {
        "rectangles": {
           "data": []
        },
        "polygons": {
           "data": []
        },
        "lines": {
           "data": []
        },
        "cuboids": {
           "data": []
        },
        "landmarks": {
           "data": []
        }
    }
   },
   "work_flow_id":"2aae1234-acac-1234-eeff-12a22a237bbc"
}

Each object in the data.maker_response.rectangles.data list will be an annotation object of the respective annotation type. For example:

Rectangle

{
  "_id": "0e6d895e-2484-439a-b62b-d8a0afb3d190",
  "label": "Cat".
  "attributes": {
    "pose": {
      "value": "standing"
    },
    "breed": {
      "value": "Persian"
    }
  },
  "coordinates": [
    {"x": 0.00398, "y": 0.00558},
    {"x": 0.05404, "y": 0.00558},
    {"x": 0.05404, "y": 0.09096},
    {"x": 0.00398, "y": 0.09096}
  ]
}

Polygons

Lines

Cuboids

Landmarks

In our annotation output, the x and y coordinates are normalised to ensure consistency across different image sizes. Normalisation is crucial for accurately representing object positions relative to the image dimensions.

X and Y Coordinates:

• X Coordinate:

  • Normalised x coordinates ($Xnorm​$) are calculated using the formula: $Xnorm = Xraw / Image Width$

  • The result ranges from 0.0 to 1.0, where 0.0(Origin) corresponds to the leftmost edge of the image, and 1.0 corresponds to the rightmost edge.

• Y Coordinate:

  • Normalised y coordinates ($Ynorm​$) are calculated using the formula: $Ynorm = Yraw / Image Height$

  • The result ranges from 0.0 to 1.0, where 0.0(Origin) corresponds to the topmost edge of the image, and 1.0 corresponds to the bottommost edge.