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...

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). Use either number or offsets, not both.
[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

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