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
Parameter | Type | Description |
---|---|---|
time | float | The time (in seconds) of the video timeline where the image should be pulled. Defaults to the middle of the original video. |
width | int32 | The width of the thumbnail (in pixels). Defaults to the width of the original video. |
height | int32 | The height of the thumbnail (in pixels). Defaults to the height of the original video. |
rotate | int32 | Rotate the image clockwise by the given number of degrees. Valid values are 90 , 180 , and 270 . |
fit_mode | string | How to fit a thumbnail within width + height. Valid values are preserve , stretch , crop , smartcrop , and pad (see below). |
flip_v | boolean | Flip the image top-bottom after performing all other transformations. |
flip_h | boolean | Flip 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
Parameters | Type | Description |
---|---|---|
start | float | The time (in seconds) of the video timeline where the animated GIF should begin. Defaults to 0. |
end | float | The 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. |
width | int32 | The 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. |
height | int32 | The height in pixels of the animated GIF. The default height is determined by preserving aspect ratio with the width provided. Maximum height is 640px. |
fps | int32 | The 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
Updated about 1 month ago