# Create a job

## A JOB

<mark style="color:green;">`POST`</mark> `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 | <p>A batch is a way to organize multiple jobs under one <code>batch\_id</code>.  You can create new batches from the dashboard or by using the batch creation API.<br><br>If <code>batch\_id</code> is left empty or the key is not present, the job is created in the <code>Default batch</code> in your project.</p> |
| 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                                                                                                                                                                                                                                                                                       |

{% tabs %}
{% tab title="200 " %}

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

{% endtab %}
{% endtabs %}

## Payload

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

## Payload Definition

| Key                      | Type     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `data.video_data.frames` | `array`  | <p>This contains an array of objects, with each object containing two properties:<br><code>frame\_id</code> - Unique identifier for the frame.<br><code>src</code> - URL of the image.</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `data.reference_data`    | `Object` | <p>The <code>reference\_data</code> object contains an additional list of images that can be used as a reference while annotating the primary image.<br>This is an <code>optional</code> key based on your requirement.<br><code>data.reference\_data.vector.images</code> is an array of objects, each containing two properties: <code>frame\_id</code> and <code>data</code>.<br><code>frame\_id</code> is a unique identifier for the frame, which will be used to map reference image(s) with the main image.<br>Each element of the <code>data</code> array contains two properties: label and image\_url.<br><code>image\_url</code> - URL of the image.<br><code>label</code>- Name of the image.</p> |

### Code Example

{% tabs %}
{% tab title="Python" %}

```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
 
    frames = ["https://example.com/image_url_1","https://example.com/image_url_2","https://example.com/image_url_3"]
    
    #reference_id should be unique for each job
    reference_id= "job1"

    project_id = ''
    x_api_key = ''
    workflow_id = ''
    batch_id = ''
    

    video_data = {'frames' : []}

    i=0
    for frame_url in frames:
        i=i+1
        frame_id = "frame"+str(i)      
        frame_obj = {'src':frame_url,'frame_id':frame_id}
        video_data['frames'].append(frame_obj)
		    job_data = {
		        'reference_id': reference_id,
		        'workflow_id': workflow_id,
		        'batch_id': batch_id,
		        'data': {
		            'video_data': video_data,
		            'reference_data': {
		                'vector': {
		                    'images': [
		                        {
		                            'frame_id': 'frame1',
		                            'data': [
		                                {
		                                    'label': 'camera 1',
		                                    'image_url': 'https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+1'
		                                },
		                                {
		                                    'label': 'camera 2',
		                                    'image_url': 'https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+1'
		                                }
		                            ]
		                        },
		                        {
		                            'frame_id': 'frame2',
		                            'data': [
		                                {
		                                    'label': 'camera 1',
		                                    'image_url': 'https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+2'
		                                },
		                                {
		                                    'label': 'camera 2',
		                                    'image_url': 'https://s3.aws.com/600x400/000/fff.jpg&text=Dummy+Image+2'
		                                }
		                            ]
		                        }
		                    ]
		                }
		            }
		        }
		    }
		    

    
    response = create_job(project_id=project_id, data=job_data, x_api_key= x_api_key)
    print(response)
    
```

{% endtab %}
{% endtabs %}

## 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

```javascript
{  
   "reference_id":"001",
   "data":{
     "video_data": {
      "frames": [...]
     },
     "maker_response" : {
        "video2d": {
           "data": {
              "annotations": []
           }
        }
     }
   },
   "work_flow_id":"2aae1234-acac-1234-eeff-12a22a237bbc"
}
```

The `data.maker_response.video_2d.data.annotations` list contains objects, where each object is a *tracker*. A tracker tracks an object across frames. The `frames` key in the tracker object maps each *annotation object* in the tracker to the `frame_id` it belongs to.&#x20;

```javascript
{
  "_id": "",
  "type": "rectangle", // rectangle/polygon/line/cuboid/landmark
  "label": "Cat",
  "frames" : {
    "frame001" : {<annotation_object>}
  }
}
```

You can check the structure for various `annotation_object` below:

{% tabs %}
{% tab title="Rectangles" %}

```javascript
{
  "_id": "0e6d895e-2484-439a-b62b-d8a0afb3d190",
  "label": "".
  "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}
  ]
}
```

{% endtab %}

{% tab title="Polygon" %}

```javascript
{
  "_id": "8f8897ad-e07b-4e55-9dbe-61f6b9df85c5",
  "label": "face_mask",
  "attributes": {
    "covers_nose": {
      "value": "Yes"
    },
  }
  "points": {
    "p1": {"x": 0.286774, "y": 0.892502},
    "p2": {"x": 0.385849, "y": 0.576888},
    "p3": {"x": 0.426721, "y": 0.469081},
    "p4": {"x": 0.288623, "y": 0.253878},
    "p5": {"x": 0.148623, "y": 0.353878}
  },
  "edges": {
    "e1": ["p1", "p2"],
    "e2": ["p2", "p3"],
    "e3": ["p3", "p4"],
    "e4": ["p4", "p4"],
    "e5": ["p5", "p1"]
  }
}
```

{% endtab %}

{% tab title="Line" %}

```javascript
{
  "_id": "8f8897ad-e07b-4e55-9dbe-61f6b9df85c5",
  "label": "lane_divider",
  "attributes": {
    "raised": {
      "value": "Yes"
    },
  }
  "points": {
    "p1": {"x": 0.286774, "y": 0.892502},
    "p2": {"x": 0.285849, "y": 0.876888},
    "p3": {"x": 0.286774, "y": 0.869081},
    "p4": {"x": 0.288623, "y": 0.853878}
  }
}
```

{% endtab %}

{% tab title="Cuboid" %}

```javascript
{
  "_id": "8f8897ad-e07b-4e55-9dbe-61f6b9df85c5",
  "label": "Car",
  "attributes" : {
    "faces_visible": {
      "value": ["right","back"]
    }
  },
  "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"]
  },
  "side": {
    "coordinates": ["p2","p3","p5","p6"]
  },
  "back": {
    "coordinates": ["p7","p8","p5","p6"]
  }
}
```

{% endtab %}

{% tab title="Landmark" %}

```javascript
{
  "_id": "e7e3353f-2ffe-432a-a14f-9cb9a6f4b735",
  "label": "nose",
  "attributes": {
    "visible": {
      "value": "Partially"
    },
  }
  "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 }
  }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
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.
    {% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://annotationdocs.telusinternational.com/video-annotation/create-a-job.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.