Quick Start: Zencoder

The heart of Zencoder is its encoding service. Taking your video-on-demand (VOD) content as input, Zencoder encodes it, producing outputs with the format and other settings you specify, and delivers them to the destination(s) of your choice. In this introduction, you will learn how to submit a basic job.

Zencoder API

All operations are carried out using the Zencoder API. Although there is a Request Builder that you can use to try out some basic API requests, you will likely soon move on to accessing API directly. In this guide, you can modify and use the cURL commands shown below, or a REST API client such as Postman.

If you are not familiar with cURL, see Set up cURL.

Make a request

The request to submit a job is a POST request sent to:

https://app.zencoder.com/api/v2/jobs

Required headers

There are two headers that must be sent along with the request:

  • Zencoder-Api-Key: YOUR_API_KEY
  • Content-Type: application/json

You can get your API key by visiting https://app.zencoder.com/api. For this exercise, you can use a Full Access or Integration-Only key.

More Information

The request may (and usually would) include output settings for the job, including an output destination, notification settings, and transcoding settings. In this simple exercise, we will skip this, but you can find more information in the Encoding Settings.

We currently support downloading files using HTTP/HTTPS, S3, Cloud Files, FTP/FTPS, SFTP, and Aspera.

A simple new job request just needs to specify the URL of the input file in the body, plus your account's API key in a header called Zencoder-Api-Key .

  {
  "input": "s3://zencodertesting/test.mov"
  }

You can test this with the following cURL command.

  curl --header "Zencoder-Api-Key: YOUR_API_KEY" \
       --header "Content-Type: application/json" \
       --data '{"input":"s3://zencodertesting/test.mov"}' \
       https://app.zencoder.com/api/v2/jobs
  

Copy this code to a text editor and replace YOUR_API_KEY with your API key. Then open a command prompt, copy and paste the cURL command at the command prompt, and press Return (Enter).

Note for Windows users: Due to a limitation in cURL on Windows you'll need to escape double quotes like \" and wrap the --data content in double quotes instead of single quotes.

This request will create an encoding job for the account and attempted to download and transcode the file at s3://zencodertesting/test.mov to the default output destination.

Response

When you create a new encoding job through the API, our server will immediately respond with details about the job and output files being created. You should store the job and outputs IDs to track them through the encoding process. Note that the id is an integer in the 64-bit range.

The data will be returned in the JSON format.

The previous new encoding job example would return the following, with a 201 Created status code.

  {
    "id": 366118847,
    "outputs": [
      {
        "id": 1297606670,
        "label": null,
        "url": "https://zencoder-temp-storage-us-east-1.s3.amazonaws.com/o/20170422/69a1a537e5b40f91c172e6b033827159/9ea8d51bc1a71545eb9c700c0379e950.mp4?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI456JQ76GBU7FECA%2F20170422%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20170422T214927Z&X-Amz-Expires=86399&X-Amz-SignedHeaders=host&X-Amz-Signature=9c0b05565dabcd5d7405a882956ef2babff6173c80cbafa36b2bd12df569e594"
      }
    ]
  }

Note: A job may still fail because the input file does not exist, the output location is invalid, the file itself is , or other reasons.