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

April 13, 2021 - Erikka Innes in Video - Pick a Thumbnail, Python

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.

Prerequisites

api.video account - Sign up here.
A video to add a thumbnail to - Free sample videos
Python installed with the requests library

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:

Upload a video to your api.video dashboard if you haven't already. You have a few choices for how to accomplish this:
- Use the GUI to add a video to your dashboard
- If your video is under 128 MB, use these instructions for upload.
- If your video is over 128 MB, you can use the Upload a Big File Using Python tutorial.
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.

import requests

# Get your authentication 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")

url = "https://ws.api.video/videos"

# Create a function to handle pagination and return videos in a list 

def paginated_response(url, token):
    headers = {
    "Accept": "application/json",
    "Authorization": token
    }
    json_response = requests.request("GET", url, headers=headers, params={})
    json_response = json_response.json()
    total_pages = 1
    if json_response is not None:
        total_pages = json_response['pagination']['pagesTotal']
    video_info = list(json_response['data'])
    if total_pages > 1:
        for i in range(2, total_pages +1):
            querystring = {"currentPage":str(i), "pageSize":"25"}
            r = requests.request("GET", url, headers=headers, params=querystring)
            r = r.json()
            video_info = video_info + r['data']
    return video_info

videos = paginated_response(url, token)

# Print out the list of videos so you can choose the one you want
print(videos)

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:

import requests 

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")

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

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

payload = {
    "timecode": "00:00:30:000"
}

response = requests.request("PATCH", url, headers=headers, json=payload)

print(response.text)

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:

import request 

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")

url = "https://ws.api.video/videos/VIDEOIDHERE/status"

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

response = requests.request("GET", url, headers=headers)

response = response.json()

print(response['encoding']['metadata']['duration'])

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:

import requests 
import datetime

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

# Get your authentication token
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")

# Get the video duration
url = "https://ws.api.video/videos/VIDEOIDHERE/status"

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

response = requests.request("GET", url, headers=headers)

response = response.json()

vid_duration = response['encoding']['metadata']['duration']

vid_halfway = vid_duration // 2

timecode = str(datetime.timedelta(seconds=vid_halfway) 

payload = {
     "timecode": timecode
}

response = requests.request("PATCH", url, headers=headers, json=payload)

print(response.text)