Video streaming is the most common way for users to consume video content. Efficient video streaming is achieved through optimizations like segmenting videos into different framerates for smooth playback, even when network bandwidth changes. Such optimizations are done by encoding the video.

This Quickstart shows how to programmatically encode your first video for streaming using Bitmovin's simplified REST API.

Through this Quickstart, you will learn how to make REST requests that:

• encode a .mov video from a publicly-accessible GCS folder to DASH format; and
• store the resulting DASH video, audio, and manifest files in Bitmovin's Content Delivery Network (CDN) – an optional storage system you can use that removes the need to set up your own cloud storage.

These requests can be embedded into apps to build complex tools, such as those used in video processing pipelines.

The following subsections describe everything necessary to perform this process:

• Prerequisites
• Step 1 – Copy Your Bitmovin API Key
• Step 2 – Create an Encoding Job
• Step 3 – Monitor the Encoding Process
• Step 4 – Locate your Encoded Video

Prerequisites

The following items are required to complete this tutorial:

• Bitmovin Account. You can create a free trial account here.
• A tool or application to invoke REST requests (e.g., Postman, cURL, etc.).

Step 1 – Copy Your Bitmovin API Key

You will need your Bitmovin API key in order to use the simplified API. Follow the steps below to find the key in your Bitmovin dashboard:

1. Open your Bitmovin dashboard in a browser and log in.
2. Click your name at the top right and select Account Settings:

3. Locate the API Keys section on the right and click Copy to copy your API key:

You will use this API key when making the REST requests in the sections below.

Step 2 – Create an Encoding Job

The first step is to start an encoding job using POST /encoding/simple/jobs/vod. This tells our cloud-based encoder what video to encode, the codec to use, and the location to store the encoded files.

The parameters in this example configure the request as follows:

• x-api-key: Your API key from Step 1 above.
• encodingTemplate: Video codec, in this case H264.
• inputs: URL(s) of the videos to encode. This example uses a publicly-access video that we provide.
• outputs: URL(s) of the location(s) to place the encoded video files. In this example, type is set to CDN which means the encoded video files will be placed on Bitmovin's CDN.

Request

POST /v1/encoding/simple/jobs/vod HTTP/1.1
Host: api.bitmovin.com
x-api-key: 59f4c...
Content-Type: application/json
Content-Length: 290

{
    "name": "Getting Started Encoding",
    "encodingTemplate": "H264",
    "inputs": [
        {
            "url": "https://storage.googleapis.com/bitmovin-sample-content/tears_of_steel_1080p.mov"
        }
    ],
    "outputs": [
        {
            "type": "CDN"
        }
    ]
  }

curl --location --request POST 'https://api.bitmovin.com/v1/encoding/simple/jobs/vod' \
--header 'x-api-key: 59f4c...' \
--header 'Content-Type: application/json' \
--data-raw '{
    "name": "Getting Started Encoding",
    "encodingTemplate": "H264",
    "inputs": [
        {
            "url": "https://storage.googleapis.com/bitmovin-sample-content/tears_of_steel_1080p.mov"
        }
    ],
    "outputs": [
        {
            "type": "CDN"
        }
    ]
  }'

📘

Notes

• By default, this request generates encodings in both DASH and HLS.
• If a URL requires credentials to access, you can include them via a credentials field. For example, the following shows how to set the access and secret keys to access a video stored in an S3 bucket:

...
"inputs": [
    {
        "url": "s3://my-bucket/path/file.mp4",
        "credentials": {
            "accessKey": "S3_INPUT_ACCESS_KEY",
            "secretKey": "S3_INPUT_SECRET_KEY"
        }
    }
],
...

Response

The data > result > status field indicates the status of the encoding job. In the example below, the value CREATED indicates the job has been created and is waiting to be processed by Bitmovin's cloud-based encoder:

{
    "data": {
        "result": {
            "id": "4dd6ca...",
            "status": "CREATED",
            "name": "Getting Started Encoding",
            "encodingTemplate": "H264",
            "inputs": [
                {
                    "url": "https://storage.googleapis.com/bitmovin-sample-content/tears_of_steel_1080p.mov"
                }
            ],
            "outputs": [
                {
                    "type": "CDN"
                }
            ],
            "errors": [],
            "createdAt": "2022-06-03T17:35:40Z",
            "modifiedAt": "2022-06-03T17:35:40Z"
        }
    },
    "requestId": "752c761...",
    "status": "SUCCESS"
}

Step 3 – Monitor the Encoding Process

After invoking the encoding API to start encoding the video, you will need to monitor the encoding until it completes. Once complete, you can then access the video for playback.

The following subsections describe how to monitor the progress of the encoding:

• Monitor the Encoding Programmatically
• Monitor the Encoding in the Dashboard

Monitor the Encoding Programmatically

Invoke GET /encoding/simple/jobs/vod/{simple_encoding_job_id} setting the simple_encoding_job_id path parameter to the value of data > result > `id returned in Step 2:

Request

GET /v1/encoding/simple/jobs/vod/4dd6ca... HTTP/1.1
Host: api.bitmovin.com
x-api-key: 59f4c...
Content-Type: application/json

curl --location --request GET 'https://api.bitmovin.com/v1/encoding/simple/jobs/vod/4dd6ca...' \
--header 'x-api-key: 59f4c...' \
--header 'Content-Type: application/json'

Response

The value of data > result > status will be RUNNING while the encoding is in progress. Once complete, the status returned will be FINISHED. You can repeatedly call this endpoint until the process ends (see Simple Encoding API - VoD) for a full list of status values.

{
    "data": {
        "result": {
            "id": "4dd6ca...",
            "status": "FINISHED",
            "encodingId": "61d9ae1...",
            "name": "Getting Started Encoding",
            "encodingTemplate": "H264",
            "inputs": [
                {
                    "url": "https://storage.googleapis.com/bitmovin-sample-content/tears_of_steel_1080p.mov"
                }
            ],
            "outputs": [
                {
                    "type": "CDN"
                }
            ],
            "errors": [],
            "createdAt": "2022-06-03T17:35:41Z",
            "modifiedAt": "2022-06-03T17:35:41Z"
        }
    },
    "requestId": "79707af...4",
    "status": "SUCCESS"
}

Monitor the Encoding in the Dashboard

Follow the steps below to monitor the progress of the encoding from the Bitmovin dashboard:

1. Open a browser and navigate to: https://bitmovin.com/dashboard.

2. Navigate to the menu bar on the left and select Encoding > Encodings.

3. Locate your encoding by name in the Encodings list and click on it. The name corresponds to that which you provided when you created the encoding job:

The encoding details screen displays and the Event Timeline section which updates as encoding progresses:

Step 4 – Locate your Encoded Video

Once encoding is complete, you'll need to get the full URL of the generated manifest (.mpd) file in order to play the video.

Follow the steps below to locate this file in the dashboard:

1. Ensure the encoding screen for your encoding is displayed as per the Monitor the Encoding in the Dashboard section above and click on the Manifests tab:

2. Locate the manifest in the list and click on the copy icon. In this example, the copy button is highlighted for the DASH version of the encoding:

3. (Optional) Click on the Details link to the left of the URL to drill down into the encoded video files.

You now have the link needed to play back the encoded video.

Next, move on to the Playback Quickstart for JavaScript v2 tutorial where you'll learn how to embed and playback the video from a simple web page.