The videos and webinars on your TwentyThree account each has a still image to represent then when shown on overview pages or inside your video player before playback has started. In TwentyThree, these images are called thumbnails (for videos) and preview images (for webianrs).

For the individual videos and webinars you can easily set up what image to use as thumbnail or preview image, and for videos you can even select a frame directly from the video to be used.

When building your video section or interfacing with the TwentyThree API, you always have immediate access to urls pointing to thumbnails and preview images in the formats and sizes that has been setup under "Design" → "Thumbnails" in the backend of your video website. These urls are available directly on the photo or live objects in Liquid templates, and they are returned as properties on objects returned on requests to the  /photo/list and /live/list endpoints:

Video thumbnails

In Liquid templates, the thumbnail_url property of the photo object points to the thumbnail in the size that has been chosen for the layout block in question. To get thumbnails in the rest of the predefined sizes, the photo objects has properties like small_download, standard_download and medium_download which each contains the url to a thumbnail in the corresponding size.

Webinar preview images

For webinars preview images are available on the live object, both in Liquid templates and through the API. The property names has the format of preview_<size>_download, thus the properties preview_small_download, preview_standard_download and preview_medium_download will provide you with urls to the small, standard and medium sizes, respectively, of the the preview image.

Custom thumbnails and preview images

Sometimes, you may need a thumbnail or preview image in a size that is not set up in your thumbnail settings. For this purpose, you can specify the size directly in the url of the image on the following form:

https://video.example.com/<tree_id>/<photo_id>/<token>/<width>x<height>/thumbnail.png

Custom video thumbnails

https://video.example.com/<tree_id>/<photo_id>/<token>/<width>x<height><cropping_method>:<time>/thumbnail.png

The tree_id, photo_id and token values are all available on the photo object (in Liquid templates and through the API) - the rest of the values is where you specify the properties of the thumnails that you are loading:

width & height: Through these values, you choose the pixel dimensions of the image. If you specify both of these value, the returned image will have those exact dimensions. However, you can omit either of the values if you want the omitted value to be automatically set to fit the aspect ratio of the video. Examples: 400x225 - The image will be 400 pixels wide and 225 pixels high 400x - The image will be 400 pixels wide, and the height will be automatically set to fit the video's aspect ratio x225 - The image will be 225 pixels high, and the width will be automatically set to fit the video's aspect ratio

cropping_method: If you have provided both a width and a height value, the cropping method determines how the image is scaled to fit the exact dimensions that you have specified, in case the dimensions do not exactly match the aspect ratio of the video. You can choose between the following values: cr - The image is cropped to the horizontally and vertically centered part of the image that has the specified dimensions. This is the default cropping method being used if you do not specify another method. st - The image is stretched to fit the dimensions, meaning that no part of the image is cropped away. mtw - The image is padded/letter boxed with solid white either on the top and bottom or the left and right to fit the dimensions. With this method, you always get an uncropped and unstretched version of the image, possibly surrounded by solid white bars. mtb - Same as mtw except the image is padded with solid black bars instead of white.

time: This value allows you to specify a duration in seconds for a place in the video where you wish to grap a frame to be used as the thumbnail image. This value is optional, but if you choose to specify it, it must be prefixed with a colon (:). If no value is specified, the normal thumbnail image is used. :10 - Grab a frame 10 seconds into the video to be used as thumbnail image

Custom webinar preview images

http://video.example.com/<preview_tree_id>/<preview_photo_id>/<preview_token>/<width>x<height><cropping_method>/thumbnail.png

The format for webinars preview image urls is almost the same as for video thumbnails. The tree_id, photo_id and token values is substituted by preview_tree_id, preview_photo_id and preview_token values which are all available on the live object, both in Liquid templates and through the API. Furthermore, the time value is not supported for webinars so it should simply be ommitted.