Tutorials · 3 min read

Photo by Fausto Marqués on Unsplash

Choose a thumbnail with api.video's pick a thumbnail endpoint

Learn how to use api.videos pick a thumbnail endpoint to choose a thumbnail to display without having to upload an image separately. Also includes where to find the video duration.

Erikka Innes

April 13, 2021

There are several ways you can add a thumbnail to your video content with api.video. If you're doing a live stream, you can add one with the Upload a Thumbnail endpoint for live streams (I go over how to do that with Python here - How to Add a Thumbnail to Your Live Stream). If you want to choose and add a thumbnail for a video yourself, you can do that with Python and FFMPEG (tutorial available here). And you can also add a thumbnail by telling the api.video API what frame you want to use. api.video will then set that frame for you. If you choose a frame that's not within the range of your video, the default will be selected, which is the frame at 00:00:00:000.


You can also check out the API reference documentation for video thumbnails here: Upload a thumbnail

Upload Your Video and Retrieve the videoId

To add a thumbnail, you first need to choose a video you want to add a thumbnail to. Do the following:

  1. Upload a video to your api.video dashboard if you haven't already. You have a few choices for how to accomplish this:

  2. If your video is already uploaded, you can retrieve the videoId from your dashboard, or you can use the list all videos endpoint to retrieve and browse through your videoIds for the one you need. I've included the code for retrieving videos here, if you need it.


Add a Thumbnail

To add a thumbnail, you have a few ways you can do things. If you wanted something you could repeat in bulk for each video, then you'd need to choose a spot that you always choose the thumbnail from. You could plan to always choose a thumbnail from five seconds into each video, but what if the video were shorter? While that's unlikely, if this were to occur, api.video automatically adds a thumbnail from 00:00:00:00.

The code for adding your thumbnail looks like this:


Add a Thumbnail from Halfway Through the Video

We just saw how to add a thumbnail to a video, and learned how the thumbnail defaults. But what if we wanted to create a thumbnail that's always about halfway through our video? We can use the Show video status endpoint to retrieve the length of the video in seconds.

Here's the code for retrieving the length of the video:


The duration will be returned in seconds. You can divide this in half using '//' in python to get an integer, and then create the timecode using the datetime library.

The code to set up your request with everything, including a timecode, would look like this:


You can add thumbnails this way for any video. Happy coding!

Try out more than 80 features for free

Access all the features for as long as you need.
No commitment or credit card required

Video API, simplified

Fully customizable API to manage everything video. From encoding to delivery, in minutes.

Built for Speed

The fastest video encoding platform. Serve your users globally with 140+ points of presence. 

Let end-users upload videos

Finally, an API that allows your end-users to upload videos and start live streams in a few clicks.


Volume discounts and usage-based pricing to ensure you don’t exceed your budget.