API Reference

Encoding videos for Web and Mobile devices

This tutorial will teach you how to encode videos to multiple formats with Coconut's API.

We are going to write a simple config file that describes the source file location and all the output formats we want. Then, we will submit it with just a few lines of code.

The config file

The config file uses a very simple format that is very easy to read and maintain. It's mainly composed of keys / values with simple keywords.

Now it's time to open your favorite text editor and create the config file coconut.conf.

Declaring our first variable

For our tutorial, we want every transcoded videos to be uploaded to an S3 account. So to keep things DRY, we will define our AWS S3 bucket URL in a variable so we can use it in all output formats without repeating ourselves.

To declare a variable, you have to use the special keyword var.

var access_key = accesskey # AWS access key
var secret_key = secretkey # AWS secret key
var bucket = mybucket
var s3 = s3://$access_key:$secret_key@$bucket/videos

To use a variable, just call it $varname anywhere in the config file.

Setting the source video location and the webhook URL

Every settings must be prefixed with the special keyword set. So let's define the source video location:

set source = http://media.s3.amazonaws.com/demo.mp4

Note that we support http(s), ftp and sftp protocols as source.

Next, we want to define the webhook URL which will be called when the job is completed:

set webhook = http://yourserver.com/webhooks/coconut

Read our tutorial on how to manage webhooks server-side.

Inspecting Webhooks

To debug and inspect the POST request, we suggest you to use our Webhook Inspector.


Encoding the video to multiple formats

To define an output, use the special keyword -> followed by the format you want.

Let's see how to encode the video to MP4 and WebM for the web and another MP4 version (lower quality) for mobile devices:

# This is the $s3 variable we declared earlier
-> mp4 = $s3/web/video.mp4
-> webm = $s3/web/video.webm
-> mp4:360p = $s3/mobile/video.mp4

For each output (->), we set the destination which is an URL where you want the encoded videos to be uploaded to. In our example we used Amazon S3, but we support many other CDNs and protocols.

Submitting the config file

The config file looks like this so far:

# Variable declarations
var access_key = accesskey # AWS access key
var secret_key = secretkey # AWS secret key
var bucket = mybucket
var s3 = s3://$access_key:$secret_key@$bucket/videos

# Setting the source file to convert and the webhook URL
# to be notified when the job is complete
set source = http://media.s3.amazonaws.com/demo.mp4
set webhook = http://yourserver.com/webhooks/coconut

# We define all the output formats and their associated
# destination URLs
-> mp4 = $s3/web/video.mp4
-> webm = $s3/web/video.webm
-> mp4:360p = $s3/mobile/video.mp4

Here is the curl command to create the job:

curl https://api.coconut.co/v1/job \
-u api-key: \
-T coconut.conf

We provide a number of client libraries to make requests very easily, so be sure to check them out.

That concludes the first tutorial on how to encode videos with Coconut. If you want to go further, you can read the full documentation. There is always our FAQ if you have any questions.


A video without a cool picture to show off is not very attractive, so be sure to read our next tutorial on how to generate thumbnails and animated GIFs.