API Reference

Generating cool video previews for your users

This tutorial follows our article about How to encode videos. You should read it first if you haven't.

Without a cool thumbnail, a video is not as attractive as it could be, that's why we provide a number of features to make the difference.

Before getting started, let's declare some variables to keep things DRY and easier to maintain. Open your text editor, create a config file coconut.conf:

var s3 = s3://accesskey:secretkey@mybucket/demo
var num = 3 # number of thumbnails we want to generate

Then, we set the source video location:

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

Note that you can edit the config file from the previous tutorial if you want.

Static thumbnails

What we are going to do is simple: we will generate 3 small and 3 large thumbnails that will be uploaded to our S3 bucket. Small thumbnail size will be 200px wide and large ones 640px wide.

-> jpg:200x = $s3/thumbnails/small/demo_#num#.jpg, number=$num
-> jpg:640x = $s3/thumbnails/large/demo_#num#.jpg, number=$num

As you notice, we used the #num# specifier in the filenames for the sequence number. In this example, the filenames will become: demo_01.jpg, demo_02.jpg and demo_03.jpg

As we already saw in the first tutorial, we used the convenient variables $s3 and $num to not repeat ourselves and to keep things organized.

Going further with static thumbnails

We have developed a number of features to beautify your thumbnails such as filters à la instagram, square format, border, rotation and shadow, so your thumbnails are unique. See a comparison below:

thumbnail with filters

Cool right? Let's see how to do this:

-> jpg:500x500 = $s3/thumbnails/postcard/demo_#num#.jpg, square=true, filters=surrealistic, border_width=20, shadow=true

We applied the filter surrealistic, added a white border of 20px, a drop shadow, and cropped the image to square format. The result should look great. Try testing different filters and settings to have the perfect picture.

You can have a look at the full documentation.

Animated GIFs: a must to attract your users

Animated GIFs are so trendy today that it's a big plus to use them to display a preview of a video.

animated GIF

As always, it's really easy, we're doing all the heavy work from generating the GIF to optimizing it for you.

-> gif:300x = $s3/animation.gif

You can have a look at the documentation for more information.

Storyboard: get an insight of the video in one picture

Storyboards are a neat way of getting insights into the video content. By looking at 8 pictures max, your users should have a good idea of what the video is about and whether they would like to watch it or not.

Storyboard

-> storyboard:640x = $s3/storyboard.png

For more information, you can read the full documentation.

Submitting the config file

This is how the config file looks so far:

var s3 = s3://accesskey:secretkey@mybucket/demo
var num = 3 # number of thumbnails we want to generate

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

# We suggest you to use our Webhook Inspector https://app.coconut.co/tools/webhooks
# to inspect the POST request we send. Very handy for testing
set webhook = http://yourserver.com/webhook/coconut

-> jpg:200x = $s3/thumbnails/small/demo_#num#.jpg, number=$num
-> jpg:640x = $s3/thumbnails/large/demo_#num#.jpg, number=$num
-> gif:300x = $s3/animation.gif
-> storyboard:640x = $s3/storyboard.png

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 our tutorial about creating attractive and awesome video previews.


The number of mobile users has increased making it essential to make your videos easily viewable under any conditions. In the Next tutorial, we will show you how to provide HTTP Live Streaming videos for iOS and android devices