API Reference 2.0

Generate static thumbnails and animations

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 WebP animation with multiple scenes:

{
  "outputs": {
    "jpg:480x": {
      "key": "jpg:medium",
      "path": "/jpg/medium/thumbs_%05d.jpg",
      "number": 10
    },
    "jpg:120x": {
      "key": "jpg:tooltip",
      "path": "/jpg/tooltip/image.jpg",
      "interval": 10,
      "sprite": {
        "columns": 10,
        "limit": 100
      },
      "vtt": {
        "filename": "thumbs.vtt"
      }
    },
    "webp_anim:320x320": {
      "key": "webp:preview",
      "path": "/webp/preview.webp",
      "scene": {
        "number": 5,
        "duration": 1
      },
      "square": true
    }
  }
}

‍

Parameters

NameTypeDefaultRequired
path
The path including the filename where the file will be uploaded. See Storage.
In case of multiple thumbnails, you must add a sequence number variable (printf style) to the filename like %05d		 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, PNG and WebP format

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

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

Example

{
  "outputs": {
    "jpg:240x": {
      "key": "jpg:small",
      "path": "/jpg/small/thumbs_%05d.jpg",
      "number": 10
    },
    "jpg:480x": {
      "key": "jpg:medium",
      "path": "/jpg/medium/thumbs_%05d.jpg",
      "number": 10
    },
    "webp:960x": {
      "key": "webp:large",
      "path": "/webp/large/thumbs_%05d.webp",
      "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_%05d.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_%05d.jpg",
      "offsets": [1, 10, 30, 50, 100]
    }
  }
}

‍
interval

With interval, you specify an interval in seconds.

Here is an example of how to generate multiple sprite files and a VTT file.

{
  "outputs": {
    "webp:200x": {
      "path": "/webp/thumbs_%05d.webp",
      "interval": 10,
      "sprite": {
      	"columns": 10,
        "limit": 100
      },
      "vtt": {
      	"filename": "thumbs.vtt"
      },
    }
  }
}

‍

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.		 hash No
limit
The number of image per sprite.
Minimum is 10 and maximum is 1000.		 int Yes
columns
The number of image per columns.		 int 4 No
vtt
Generate a WebVTT file that includes a list of cues with either individual thumbnail or sprite with the right coordinates		 Hash no No
filename
The VTT filename with .vtt extension.		 string Yes

Animation

Simple Format pattern: gif|webp_anim:$widthx$height

Create an animation image from the source video. Width must be <= 600px.

Example

{
  "outputs": {
    "webp_anim:480x": {
      "key": "webp:animation",
      "path": "/webp/animation.webp",
      "scene": {
        "number:" 5,
        "duration": 1
      }
    }
  }
}


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

Animation 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 animation, 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 animation image 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 600px.		 string 200x No