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

Generate static thumbnails and animated GIF

Jump to

Every outputs must be set inside the outputs key with each value being a Hash describing the output format and settings.

The format specs are named following a very simple naming convention described in the Formats page.

Examples

Generating thumbnails in JPG formats and a very cool GIF with multiple scenes:

{
  "outputs": {
    "jpg:480x": {
      "key": "jpg:medium",
      "path": "/jpg/medium/thumbs_%.2d.jpg",
      "number": 10
    },
    "jpg:120x": {
      "key": "jpg:tooltip",
      "path": "/jpg/tooltip/image.jpg",
      "interval": 10,
      "sprite": true,
      "vtt": true
    },
    "gif:320x320": {
      "key": "gif:preview",
      "path": "/gif/preview.gif",
      "scene": {
        "number": 5,
        "duration": 1
      },
      "square": true
    }
  }
}

Parameters

NameTypeDefaultRequired
path
The path including the filename where the file will be uploaded. See Destination.
In case of multiple thumbnails, you must add a sequence number variable (printf style) to the filename like %.2d
string Yes
if
If the given condition is false, the output won't be processed.
Logical operators we support are: < > <= >= <> != = AND OR NOT. See Conditional outputs.
string No
key
Will rename the output key which is sent in the notification payload. Very useful because you can change the output settings but the key name you get at the end will be unchanged. No code to update on your side.
string No
format
Set the format specs. This is totally optional since you can set all the format specs inside the output key by following the syntax described here.
hash No
resolution
Set the resolution.
Example: 1280x720, 1280x or any resolutions 240p 360p 480p 540p 576p 720p 1080p 2140p.
string Original No


Static thumbnails in JPG and PNG format

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

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

Example

{
  "outputs": {
    "jpg:240x": {
      "key": "jpg:small",
      "path": "/jpg/small/thumbs_%.2d.jpg",
      "number": 10
    },
    "jpg:480x": {
      "key": "jpg:medium",
      "path": "/jpg/medium/thumbs_%.2d.jpg",
      "number": 10
    },
    "jpg:960x": {
      "key": "jpg:large",
      "path": "/jpg/large/thumbs_%.2d.jpg",
      "number": 10
    },
    "jpg:400x400": {
      "key": "jpg:square",
      "path": "/jpg/square/image.jpg",
      "square": true
    }
  }
}

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:

{
  "outputs": {
    "jpg:240x": {
      "path": "/jpg/thumbs_%.2d.jpg",
      "number": 20
    }
  }
}


offsets

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

For example:

{
  "outputs": {
    "jpg:480x": {
      "path": "/jpg/thumbs_%.2d.jpg",
      "offsets": [1, 10, 30, 50, 100]
    }
  }
}


interval

With interval, you specify an interval in seconds.

For example:

{
  "outputs": {
    "jpg:480x": {
      "path": "/jpg/thumbs_%.2d.jpg",
      "interval": 10
    }
  }
}

Static Images Parameters

NameTypeDefaultRequired
number
Number of thumbnail you want to generate. Must be <= 100. Use either number or offsets, not both.
int 1 No
offsets
Offset(s) in second where you want to extract the thumbnail(s).
[int,] No
interval
Interval in seconds between each thumbnail.

If 0, will calculate the right gap in second according to the source video duration:
interval 2 sec if duration <= 2 min
interval 5 sec if duration <= 10 min
interval 10 sec if duration <= 30 min
interval 20 sec if duration <= 60 min
interval 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
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
blur
Make a blurred image. Value goes from 1 to 5.
int No
sprite
We group interval 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
Generate a WebVTT file that includes a list of cues with either individual thumbnail or sprite with the right coordinates
bool no No

GIF animation

Simple Format pattern: gif:$widthx$height

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

Example

{
  "outputs": {
    "gif:320x": {
      "key": "gif:preview",
      "path": "/gif/preview.gif",
      "scene": {
        "number:" 5,
        "duration": 1
      }
    }
  }
}


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.

GIF Parameters

NameTypeDefaultRequired
offset
Will start the animation from the given offset in second
int video_length / 3 No
scene
Customize how many scenes you need and the scene duration in second.
hash No
number
The number of scenes.
Maximum is 10.
int 1 No
duration
The Scene duration in second. For a more dynamic GIF, we suggest to use very short scene duration like 1sec.
Maximum is 5.
int 5 No
fit
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
square
The GIF will be cropped to a square. Use the width value to determine the size.
width and height are required.
bool false No
blur
Make a blurred image. Value goes from 1 to 5.
int No
format
Set the format specs. This is totally optional since you can set all the format specs inside the output key by following the syntax described here.
hash No
resolution
Set the resolution.
Example: 500x, 300x160.
Maximum width is 500px.
string 200x No