logo api.video

Create a Thumbnail For Your Video with Python and FFMPEG

April 14, 2021 - Erikka Innes in Videos - Upload a Thumbnail,Python

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:

import requests 
import ffmpeg
import sys

in_filename = "sample-mov-file.mov"
out_filename = "THUMBNAIL.jpg"

def generate_thumbnail(in_filename, out_filename):
    probe = ffmpeg.probe(in_filename)
    time = float(probe['streams'][0]['duration']) // 2
    width = probe['streams'][0]['width']
            .input(in_filename, ss=time)
            .filter('scale', width, -1)
            .output(out_filename, vframes=1)
            .run(capture_stdout=True, capture_stderr=True)
    except ffmpeg.Error as e:
        print(e.stderr.decode(), file=sys.stderr)

generate_thumbnail(in_filename, out_filename)

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:

import requests 

# Get api.video token 

url = "https://ws.api.video/auth/api-key"

payload = {"apiKey": "your API key here"}
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"

response = requests.request("POST", url, json=payload, headers=headers)
response = response.json()
token = response.get("access_token")

# Add the video ID you want to send a thumbnail to 

vid = "video ID here"

url = "https://ws.api.video/videos/" + vid + "/thumbnail"

headers = {
    "Accept": "application/vnd.api.video+json",
    "Authorization": token

# Add your file to use as a thumbnail 

file = {"file": open("THUMBNAIL.jpg", "rb")}

response = requests.request("POST", url, files=file, headers=headers)

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!


Erikka Innes

Developer Evangelist