Tutorials · 5 min read

Create a Thumbnail For Your Video with Python and FFMPEG

Create a thumbnail for your video with Python and FFMPEG

Learn how to create a single thumbnail for your video and add it using FFMPEG and Python!

Erikka Innes

April 14, 2021

Video thumbnails have the power to make a video more watchable. Thumbnails give people an initial impression of what your video is about. If you have time, the best thumbnail for a video is going to be one where you choose something representative of the video's content, and then add it. But sometimes, you might not have the time to manually choose the perfect thumbnail for every video you create. Sometimes, you might just want to quickly add a thumbnail that represents a frame from the video, and move on. You can easily accomplish this with FFMPEG for Python.


  • Mac that's OSX10.7 or higher (as always, you can tweak the instructions for Linux or PC if you want to try that but it's a Mac focused tutorial)
  • Homebrew - if you don't have it we'll include a little about installing it
  • Xcode - you can add this as part of a homebrew installation
  • api.video account - you can get one for FREE right here
  • Python
  • requests module for Python
  • ffmpeg-python
  • Homebrew - installation of FFMPEG is much easier with homebrew

Install FFMPEG

Sometimes an FFMPEG install can get complicated. You'll see a lot of people online asking why their installation doesn't work. If you have a Mac, there is an easy answer to this problem...hopefully. Let's go over one simple way you can install FFMPEG so it starts working at the command line for you right away. We're going to use the homebrew method, because it makes installation simple if you already have homebrew installed.

For Users Who Already Have Homebrew

If you've got homebrew installed, all you need to do is this:

brew install ffmpeg

That's it. It should install without issue. (Famous last words right?) Test that it works with this:

ffmpeg -version

If it's installed, you will get back a bunch of information about your configuration. If not you will get an error of some type. Troubleshooting installation is beyond the scope of this tutorial, but you can post questions in the community forum and we'll help you figure it out.

For Users Who Don't Have Homebrew

If you fall into this category, you may be wondering what homebrew is. It's a free, open-source software package manager. It simplifies installation of software on macOS and Linux.

To install homebrew, you'll need to run this command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

If you don't have Xcode, or the appropriate Xcode components installed, you'll have to install those. Fortunately, you'll be told what's missing so you can install it. Follow the instructions to install and if you run into problems, there is a lot of documentation online to help you through. We can't be more specific for Xcode, because there's a lot of ways your installation can differ from another one. However, if you need help, feel free to contact us in the community forum.

Thumbnail Creation Method - Using FFMPEG

You can use ffmpeg-python to create a thumbnail and upload it for use with your video. If you don't want to get into learning FFMPEG, you can also use api.video's endpoint that allows you to pick a time from the video, and have it set as the video thumbnail for you automatically.

NOTE: The thumbnail must be .jpg or .jpeg and 8MB or smaller.

If you're interested in trying it with ffmpeg-python, then here's the code:


Let's dig in a bit to what's going on here. First, to make the sample easier to work with, we have the file we want to take a thumbnail from in the folder. Our thumbnail will output to the same folder.

Next in our code, we create a function that will create a thumbnail for us. It takes the path to the file we want to grab a thumbnail from. Then we retrieve the length in seconds of our movie. Right now this function takes a thumbnail from about halfway through the video it receives. It then outputs the file, named 'THUMBNAIL.jpg' to the same folder where we can check it out if we want.

Now we're ready to upload our video and thumbnail.

Upload the Video

The code for this is straightforward. You can upload a video using one of these options:

Make sure you grab the videoId for your video.

Add Your Thumbnail

The code to add a thumbnail looks like this:


In this code, you retrieve your access token, then you set up your headers and URL. The URL must contain the videoId for the video you want to add a thumbnail to. Add your thumbnail as a binary file. You can check the json response to make sure everything was a success, and double check by looking in your dashboard at your video. Sometimes the new thumbnail populates to the video faster on the individual page for viewing that video, so give it a few minutes and then hit refresh to be sure your thumbnail was added.

You could potentially use this method with some tweaks to create a short trailer of thumbnail images. We'll go over how to do that next!

Don't hesitate to ask us questions on our community forum!

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.