Get Thumbnails and Images from Video Assets

Learn how to get images from a video to show a preview thumbnail or poster image.

Get an image from a video

To get an image from a video Asset, use the PlaybackId attribute (available via the Get Asset endpoint) to make a request to image.video-assets.kevel.com in the following format:

https://image.video-assets.kevel.com/{PLAYBACK_ID}/thumbnail.{png|jpg|webp}

Images can be served in either webp, png, or jpg format. Webp is an image format that uses lossy and lossless image compression methods to reduce image size while maintaining good quality. If your images are in the webp format, they will typically yield a smaller file size compared to using png or jpg images.

You can control how the image is created by including the following query string parameters with your request. If you don't include any, Kevel will default to choosing an image from the middle of your video.

Thumbnail Query String Parameters

ParameterTypeDescription
timefloatThe time (in seconds) of the video timeline where the image should be pulled. Defaults to the middle of the original video.
widthint32The width of the thumbnail (in pixels). Defaults to the width of the original video.
heightint32The height of the thumbnail (in pixels). Defaults to the height of the original video.
rotateint32Rotate the image clockwise by the given number of degrees. Valid values are 90, 180, and 270.
fit_modestringHow to fit a thumbnail within width + height. Valid values are preserve, stretch, crop, smartcrop, and pad (see below).
flip_vbooleanFlip the image top-bottom after performing all other transformations.
flip_hbooleanFlip the image left-right after performing all other transformations.

The fit_mode parameter can have the following values:

  • preserve: By default, Kevel will preserve the aspect ratio of the video, while fitting the image within the requested width and height. For example if the thumbnail width is 100, the height is 100, and the video's aspect ratio is 16:9, the delivered image will be 100x56 (16:9).
  • stretch: The thumbnail will exactly fill the requested width and height, even if it distorts the image. Requires both width and height to be set. (Not very popular.)
  • crop: The video image will be scaled up or down until it fills the requested width and height box. Pixels then outside of the box will be cropped off. The crop is always centered on the image. Requires both width and height to be set.
  • smartcrop: An algorithm will attempt to find an area of interest in the image and center it within the crop, while fitting the requested width and height. Requires both width and height to be set.
  • pad: Similar to preserve but Kevel will "letterbox" or "pillar box" (add black padding to) the image to make it fit the requested width and height exactly. This is less efficient than preserve but allows for maintaining the aspect ratio while always getting thumbnails of the same size. Requires both width and height to be set.

Example with Query String Parameters

Here is an example request for an image including query parameters which:

  • has a width of 400 and a height of 200
  • uses the smartcrop fit mode
  • is taken from the 35th second of the video
  • is a PNG
https://image.video-assets.kevel.com/{PLAYBACK_ID}/thumbnail.png?width=400&height=200&fit_mode=smartcrop&time=35

Note that there is a default limit of 30 thumbnails per Asset. This means you can have 30 thumbnails and 30 GIFs per Asset.

Get an animated GIF from a video

To get an animated gif or webp from Kevel, use a PlaybackId associated with an Asset to make a request to image.video-assets.kevel.com in the following format:

https://image.video-assets.kevel.com/{PLAYBACK_ID}/animated.{gif|webp}

You can control how the image is created by including the following query string parameters with your request.

Animated GIF Query String Parameters

ParametersTypeDescription
startfloatThe time (in seconds) of the video timeline where the animated GIF should begin. Defaults to 0.
endfloatThe time (in seconds) of the video timeline where the GIF ends. Defaults to 5 seconds after the start. Maximum total duration of GIF is limited to 10 seconds; minimum total duration of GIF is 250ms.
widthint32The width in pixels of the animated GIF. Default is 320px, or if height is provided, the width is determined by preserving aspect ratio with the height. Max width is 640px.
heightint32The height in pixels of the animated GIF. The default height is determined by preserving aspect ratio with the width provided. Maximum height is 640px.
fpsint32The frame rate of the generated GIF. Defaults to 15 fps. Max 30 fps.

Example with Query String Parameters

Here is an example request for a GIF including query parameters which:

  • set a width of 640
  • set a frame rate of 5fps
 https://image.video-assets.kevel.com/{PLAYBACK_ID}/animated.gif?width=640&fps=5