Add A Thumbnail To Your Video

For videos or recorded live streams, api.video offers you two ways to add a thumbnail:

Upload an image as a thumbnail
Choose a timecode in your video and use that as the thumbnail

This guide walks you through both methods for setting up a thumbnail for videos.

If you want to add a thumbnail to a live stream, the only available method is to upload a picture you choose. You can read more about this in the Add or delete a live stream thumbnail guide.

API documentation

Upload a thumbnail

You have the option to choose a photo that's in .jpg, .png, or .webp format. It must be 8MB or smaller. To send your file, add the path to where it's stored and open it in binary. Then you can upload it with the client of your choice or see how it works with cURL.

Uploading a thumbnail

curl --request POST \
     --url https://ws.api.video/videos/vi61tikT4GAAB29KehMKyqX3/thumbnail \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI1NDk1NjAuMDE5ODA0LCJuYmYiOjE2NDI1NDk1NjAuMDE5ODA0LCJleHAiOjE2NDI1NTMxNjAuMDE5ODA0LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.jjr4YADGbe62RmBBxJXLy1D61Mtfry_dq9nbriBXgkPrdlBJ8ZRP50CyW3AsGD7wSuKp2mXxEYSzj64zelT1IGOwg6KG4Gz9BZ9YWs0GAHKUIdgqn1gzITX5aQljIXx1fquXbawd-axBTi4icmaUjgXjfnyIcWOgHd2D8A3kpKiqiMmluh58JdnwPnH0OyVk0Rk824P0PI6SxfiTHfkCglPL6ixf9OgokMLPoVrsxH5C0xt3Z7lf5TJ0F78-JY-yTKvyaTTIfI6CFOMNaZUlMtgQwq8X93_2FA65Ntw3hdDML8gFKkLUxnBAtZMo9WAjUd30G4OcYasmlkc4Q_JSNw' \
     --header 'Content-Type: multipart/form-data' \
     --form file=@pic.jpg

Pick a thumbnail

If you don't want to create a custom thumbnail image for your video, you can select one from the video itself. All you need to do is choose the timecode to the frame you want to be the thumbnail. The accepted formats are:

HH:MM:SS.mm - hours, minutes, seconds, milliseconds
hh:mm:ss:frameNumber
int - integer value is reported as seconds

If your selection is out of range, 00:00:00.00 will be used.

Picking a thumbnail

curl --request PATCH \
     --url https://ws.api.video/videos/viZxSTFgXZVjFnFCUo363Ie/thumbnail \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJpYXQiOjE2NDI1NDk1NjAuMDE5ODA0LCJuYmYiOjE2NDI1NDk1NjAuMDE5ODA0LCJleHAiOjE2NDI1NTMxNjAuMDE5ODA0LCJwcm9qZWN0SWQiOiJwclJ6SUpKQTdCTHNxSGpTNDVLVnBCMSJ9.jjr4YADGbe62RmBBxJXLy1D61Mtfry_dq9nbriBXgkPrdlBJ8ZRP50CyW3AsGD7wSuKp2mXxEYSzj64zelT1IGOwg6KG4Gz9BZ9YWs0GAHKUIdgqn1gzITX5aQljIXx1fquXbawd-axBTi4icmaUjgXjfnyIcWOgHd2D8A3kpKiqiMmluh58JdnwPnH0OyVk0Rk824P0PI6SxfiTHfkCglPL6ixf9OgokMLPoVrsxH5C0xt3Z7lf5TJ0F78-JY-yTKvyaTTIfI6CFOMNaZUlMtgQwq8X93_2FA65Ntw3hdDML8gFKkLUxnBAtZMo9WAjUd30G4OcYasmlkc4Q_JSNw' \
     --header 'Content-Type: application/json' \
     --data '
{
     "timecode": "00:00:00.000"
}
'

Add a thumbnail from the dashboard

api.video enables you to add a thumbnail from the dashboard. Both choices discussed in this guide are available here too - Timestamp and Upload image.

Visit the Videos page in the dashboard to get started.
Locate the video that you want to add a thumbnail to, and click on Video Details.
On the video details page, scroll down to the section where you see Thumbnail as an option. Click on Update thumbnail.

To select a frame as a thumbnail from your video, click Timestamp. Enter the timestamp of the frame in HH:MM:SS (hours, minutes, seconds). Click Set Tumbnail.

If you're adding an image, the same file constraints apply as they do when you use the API. Click Upload image to select this method and either drag & drop, or upload a file by browsing your device. Push Upload Tumbnail to finalize.

Conclusion

There are two ways to add thumbnails - adding an image or choosing a frame from the video. Adding an image as the thumbnail is great if you want to do special branding for your video, or other elements.