If one looks at video and audio encodings like H.264, H.265, VP9, AV1 and all of the things that are associated with it, it can be very easy to get lost. There are millions of possible configurations and figuring out the right one can be a difficult task.
The Bitmovin API makes it possible to granularly tinker with your video settings and cover a vast array of use cases. This alone can become a daunting task, as setting up even a simple encoding can take a lot of time. That is why we’ve set out to make taking your first encoding step easier.
Bitmovin’s new Simple Encoding API uses our Per-Title technology to deliver the best video experience to you with little to no configuration necessary. Using the Simple Encoding API will set up a complete (and automated) encoding job for you by making use of our base API. The encoding will use an H264 codec for video inputs and an AAC stereo for audio.
*UPDATE – Feb 8, 2022* With the release of Encoder version 2.109.0, the Bitmovin Simple Encoding API now supports AV1 encoding, in addition to the default H264! Click below to try it out in Postman and check the documentation tab there for more details.
How to use the Simple Encoding API
The Simple Encoding API will help you to create an encoding that will fit a vast array of use cases with only a single endpoint. You can either use any of Bitmovin’s SDKs or directly call the endpoints with tools like Postman. For additional information on how to add the API key to the request can be found here: https://bitmovin.com/docs/encoding/tutorials/get-started-with-the-bitmovin-api.
With a single endpoint in mind, the only things that you need to set up are the inputs and the outputs.
The first thing you will need is input. The most common input types are supported: S3, GCS, Azure Blob Storage, Akamai NetStorage, HTTP(S), and (S)FTP.
You can choose between four different input types: audio, video, subtitles, and closed captions. If you don’t specifically state an input type for a file, it will be assumed to contain a video track and an optional audio track.
Multiple audio and subtitles/closed captions inputs can be used but only one video input is possible. Specifying a language is mandatory for subtitles and closed captions; as a best practice, we also recommend specifying the language for audio inputs.
Simple Encoding Output
Let’s define an input.
"inputs":[
{
"url": "https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov"
}
]
Next, we are going to define an output. The Simple Encoding API supports S3, GCS, Azure Blob Storage, and Akamai NetStorage as output, further details can be found in our documentation. One thing to consider is if the created files need to be private or public. If the files are public the output has to be able to support that.
Next, let’s set up a private S3 output.
"outputs": [
{
"url": "s3://your/output/path",
"credentials": {
"accessKey": "accessKey",
"secretKey": "secretKey"
}
}
]
Now you only need to choose a name for your encoding job and put the inputs and the outputs into one JSON. It will look somewhat like this:
{
"name": "simple_encoding_name",
"inputs": [
{
"url": "https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov"
}
],
"outputs": [
{
"url": "your/output/path",
"credentials": {
"accessKey": "accessKey",
"secretKey": "secretKey"
}
}
],
}
With the JSON completed the last thing to do is to send it to the API via this endpoint.
POST https://api.bitmovin.com/v1/encoding/simple/jobs/vod
The response will look like this
{
"id": "854a2a86-9028-4e33-863b-d602a6bac24b",
"status": "CREATED",
"encodingId": null,
"inputs": [
{
"url": "https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov"
}
],
"outputs": [
{
"url": "your/output/path",
}
],
"createdAt": 2022-01-17T14:26:54Z,
"modifiedAt": 2022-01-17T14:26:54Z,
"name": "simple_encoding_name"
}
Now that the start call is fully set up, the last thing to do is wait for the encoding to finish.
The endpoint will show the current status of your encoding
GET /encoding/simple/jobs/ vod/{simple_encoding_job_id}
{
"id": "854a2a86-9028-4e33-863b-d602a6bac24b",
"status": "FINISHED",
"encodingId": "5b71dcf1-5f92-4534-b530-47706003e7a4",
"inputs": [
{
"url": "https://ftp.halifax.rwth-aachen.de/blender/demo/movies/ToS/ToS-4k-1920.mov"
}
],
"outputs": [
{
"url": "your/output/path",
"makePublic": true
}
],
"name": "simple_encoding_name"
}
Once the status is set to “finished” the encoding is done.
The Simple Encoding API can be accessed by our SDKs as well.
Simple Encoding API output
Once the simple encoding has finished, it will write the output to your specified location. The encoding will create segmented video files as well as HLS and DASH manifests. The encoding will furthermore create thumbnails, sprites, subtitles, closed captions, and audio if your input contains them.
We know that starting your video encoding can be hard, thus we aimed to keep this API as simple as possible while still providing you with everything you might need for your workflow. We will continue to improve our Simple Encoding API, so if you have any suggestions for improvements or how we can make it more suitable for your use case, please let us know!
How to Troubleshoot the Simple Encoding API & FAQs
Error Messages
“No API key found in request”
API requests must be authenticated using your API key. This is found in the dashboard under your name (top right/Account settings). This is placed as the X-Api-Key in the header of your POST request. We suggest using a tool such as POSTMAN to create the POST request during testing
Could not determine the scheme
Output URLs follow the standard URL structure provided by the storage providers. These are written above as “your/output/path” however must also include the scheme identifier: for google this is gcs://<bucket-name>/folder, for amazon this is s3://<bucket-name>/folder, for ftp ftp://__ etc. Failure to put the <something>:// will result in this error message.
Questions
I want to the Simple Encoding API, but I don’t have an API key:
The easiest way is to sign up for a trial via the bitmovin homepage bitmovin.com / Try for free (top right)
I have submitted the POST request, the response says “SUCCESS” but nothing is appearing in the dashboard:
There may be something wrong in credentials or file locations.
- Copy the “id” found in the first line of the response
- Query it with GET /encoding/simple/jobs/vod/{simple_encoding_job_id} (where simple_encoding_job_id is the id you just copied)
- This will provide more thorough details of the simple-encoding-job.
What’s the difference between simple_encoding_job_id (referenced above) and Encoding ID (in the dashboard)?
Once a simple-encode-id-job is successfully submitted an encodeId will be assigned. You can find the encodeId for a particular simple_encoding_job_id via GET /encoding/simple/jobs/vod/{simple_encoding_job_id} and looking for encodeId in the response.
How to add different input types to the Simple Encoding request?
You can view all input types and how to use them in our documentation here: https://bitmovin.com/docs/encoding/articles/simple-encoding-api
Try out our new Simple Encoding API for yourself by signing up for a trial today.
Video technology guides and articles
- Back to Basics: Guide to the HTML5 Video Tag
- What is a VoD Platform? A comprehensive guide to Video on Demand (VOD)
- Video Technology [2022]: Top 5 video technology trends
- HEVC vs VP9: Modern codecs comparison
- What is the AV1 Codec?
- Video Compression: Encoding Definition and Adaptive Bitrate
- What is adaptive bitrate streaming
- MP4 vs MKV: Battle of the Video Formats
- AVOD vs SVOD; the “fall” of SVOD and Rise of AVOD & TVOD (Video Tech Trends)
- MPEG-DASH (Dynamic Adaptive Streaming over HTTP)
- Container Formats: The 4 most common container formats and why they matter to you.
- Quality of Experience (QoE) in Video Technology [2022 Guide]
