API documentation

Coconut's API is a config-based API built with simplicity and flexibility in mind.
Encode your first video in less than 5 minutes.

API Reference

Video previews

Keyword: outputs must be prefixed by the keyword -> followed by the format ID (type of preview).

The first value is the output URL which is the full location URL with filename where you want the image(s) to be uploaded to.

Thumbnails

Simple Format pattern: jpg|png:$widthx$height

Generate thumbnails in either jpg or png format from the source video.

Example

var s3 = s3://accesskey:secretkey@bucket/previews/thumbnails

-> jpg:300x    = $s3/thumb_#num#.jpg, number=3
-> png:600x600 = $s3/thumb_square_#num#.png, number=10, square=true
-> jpg:600x    = $s3/thumb_large.jpg

The output URL must contain the filename of the thumbnails with the special variable #num# which will be replaced by the sequence number. The sequence number is mandatory if number > 1.

#num# is equal to %.2d in printf format identifier. If you need another format identifier, you can use a decimal identifier like mythumb_%1d.jpg to have mythumb_1.jpg, mythumb_2.jpg, etc.

For instance, image names generated with filename mythumb_#num#.jpg will be: mythumb_01.jpg, mythumb_02.jpg, etc...

3 ways to generate thumbnails

number

By using the number option which is the default, you choose to generate a given number of thumbnails. The images will be spaced equally.

For instance:

-> jpg:300x = $s3/thumb_%.2d.jpg, number=20


offsets

By using offsets, you specifically select 1 or many offsets in second where you want to take the thumbnail.

For example:

-> jpg:300x = $s3/thumb_%.2d.jpg, offsets=1,10,30,50,100


every

With every, you specify a gap in second. We will generate thumbnails every X seconds.

For example:

-> jpg:300x = $s3/thumb_%.2d.jpg, every=10

Parameters

NameTypeDefaultRequired
if
If the given condition is false, the current section won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT.
string No
number
Number of thumbnail you want to generate. Must be <= 100. Use either number or offsets, not both.
int 1 No
offsets
Available since 2015-05-07

Offset(s) in second where you want to extract the thumbnail(s).
[int,] No
every
Available since 2018-10-17

Generate thumbnails every X seconds.

If 0, will calculate the right gap in second according to the source video duration:
every 2 sec if duration <= 2 min
every 5 sec if duration <= 10 min
every 10 sec if duration <= 30 min
every 20 sec if duration <= 60 min
every 30 sec if duration > 60 min
int No
square
The image will be cropped to a square. Use the width value to determine the size.
width and height are required.
bool false No
fit
Available since 2016-05-24
Option to change the fit mode. To keep the original aspect ratio by cropping instead of padding (default behavior), set fit=crop
width and height are required.
string pad No
sprite
Available since 2018-10-17

We group every thumbnails into a single image called sprite. The sprite is 4 columns wide. Best for network optimization if you have a lot of thumbnails and if you want to show tooltip like thumbnail within your player.
bool no No
vtt
Available since 2018-10-17

Generate a WebVTT file that includes a list of cues with either individual thumbnail or sprite with the right coordinates
bool no No

Animated GIF

Simple Format pattern: gif:$widthx

Create an animated GIF from the source video. Width must be < 500px.

Example

-> gif:240x = s3://accesskey:secretkey@bucket/previews/animation.gif


The GIF maximum duration is 5 seconds.

All the generated GIF files are optimized but keep in mind that the result is usually pretty fat: 1-5MB for 5 seconds. Prefer using a small width value to have good quality/size for your preview.

The height is automatically calculated according to the given width and the original aspect ratio.

Parameters

NameTypeDefaultRequired
if
If the given condition is false, the current section won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT.
string No
offset
Will start the animation from the given offset in second
int video_length / 3 No

Storyboard

Simple Format pattern: storyboard:$widthx

Generate a storyboard from the source video. Width must be < 1280px.

Example

-> storyboard:800x = s3://accesskey:secretkey@bucket/previews/storyboard.png


The number of tiles depends on two factors:

  • The width of the whole storyboard
  • The length of the video

The Storyboard image format is png and its aspect ratio is always 16/9.

Parameters

NameTypeDefaultRequired
if
If the given condition is false, the current section won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT.
string No