Tutorials · 4 min read

live stream, captivating thumbnail, upload a thumbnail

How to add a thumbnail to your live stream

Learn how to add a thumbnail to your live stream using the api.video API and Python!

Erikka Innes

March 17, 2021

A beautiful and engaging video thumbnail can help describe what your video or live stream is about and attract viewer interest. If you have ideas for a thumbnail for your live stream, but you aren't sure how to add it, the api.video API provides an easy way to include one. Let's get coding!


  • Python
  • Account with api.video
  • Live stream equipment like a camera, phone camera, web cam or similar (this tutorial uses the Mac's built in web camera)
  • Thumbnail you want to use - thumbnail must be .jpg or .jpeg and 8MB or smaller

What you'll be doing

This tutorial walks you through everything you'll need to add a thumbnail, including setting up a live stream if you didn't already do that using another tutorial or our API reference documentation. The steps are:

  1. Set up a live stream if you don't have one.
  2. Retrieve the Live Stream ID so you can make changes to the thumbnail.
  3. Add your thumbnail.

Add a live stream

To add a live stream to api.video, you create a container for the live stream, and then send your stream to it to be played. In this tutorial, we're focused on making updates to the container. If you want to actually stream, see one of the other tutorials on the topic.

The code sample for setting up the live stream container is:


Retrieve live stream ID

There are two ways to retrieve the live stream ID from your live stream:

  • Look in the dashboard
  • Send a request to api.video for a list of live streams

Look in the dashboard

This is a no-code way to get the live stream ID:

No-Code Method for Getting the Live Stream ID

  1. Open the api.video dashboard.
  2. Click My videos.
  3. Click Live.
  4. Click the live stream you want to add a thumbnail to.
  5. On the live stream's details page, under Copy code, grab the live stream ID from the end of the link there. It should be whatever comes after live/.

Get the Live Stream ID with Python You can retrieve all live stream IDs with Python and then sort through them for the live stream you wanted. If you have some information to start with, you can tweak this script to bring back live streams with attributes that match what you want. Here's the code sample for retrieving all live streams:


In our code sample, we authenticate with our API credentials, then retrieve an access token. The token is good for one hour. Next, we send a request to the live streams endpoint asking to retrieve all live streams, and print them out in the console.

You can look through what's returned to find your live stream or write additional code to retrieve and handle a specific live stream. The sample is to help get you started.

When you locate the live stream you want to add a thumbnail to, save it for the next step.

Upload a thumbnail

We're going to use the thumbnail endpoint for live streams. Place your thumbnail image in the same folder as your script. Here's the code:


Notice the code sample continues from after the first sample listed - so we assume you have your token for use authenticating with the live stream thumbnail endpoint. To make the code sample easy to follow, we also assume that you've retrieved the live stream ID you want and it's listed as the variable live.

To access a specific live stream and upload a thumbnail to it, you have to include the live stream ID in the endpoint. We build the endpoint with the line: url = 'https://ws.api.video/live-streams/' + live + '/thumbnail'

To add the image, you need to append it with this code:

    'file': ("image1.jpg", open("image1.jpg", "rb"))

You open the file using a dictionary that contains a tuple and then add it to your request.

If you successfully make the upload, you'll get back something that looks like this:

	"name":"Live Stream Title",
		"iframe":"\u003Ciframe src=\u0022https://embed.api.video/live/yourliveStreamId\u0022 width=\u0022100%\u0022 height=\u0022100%\u0022 frameborder=\u00220\u0022 scrolling=\u0022no\u0022 allowfullscreen=\u0022true\u0022\u003E\u003C/iframe\u003E","player":"https://embed.api.video/live/li1rVQ9RmyvQ2R4ae57KeEm5",
		"hls":"https://live.api.video/yourliveStreamId.m3u8",				   "thumbnail":"https://live.api.video/yourliveStreamId/thumbnail.jpg"

Check the thumbnail

To check if your thumbnail is there, go into the live streams section of your dashboard, and see if your live stream displays it.

You may also like...

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.