api.video

Features

Documentation

How to Add a Thumbnail to Your Live Stream

March 17, 2021 - Erikka Innes in Live - Upload a Thumbnail, Python

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!

Prerequisites:

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

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:

import requests

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

payload = {"apiKey": "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/live-streams"

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

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

You might recognize this code sample from the tutorial "Live Stream to the Browser with FFMPEG CLI and Python".

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:

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/live-streams"

querystring = {"currentPage":"1","pageSize":"25"}

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

response = requests.request("GET", url, headers=headers, params=querystring)
response = response.json()
print(response)

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:

import requests

live = "livestreamID"
files = { 
    'file': ("image1.jpg", open("image1.jpg", "rb"))
}

url = "https://ws.api.video/live-streams/" + live + "/thumbnail"

headers = {
    "Accept": "application/json",
    "Authorization": token
}

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

print(response.text)

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:

	"liveStreamId":"yourliveStreamId",
	"createdAt":"2021-03-05T09:25:10+00:00",
	"updatedAt":"2021-03-18T05:49:54+00:00",
	"streamKey":"7337t9e0-82d3-4258-b497-489648e10444",
	"name":"Live Stream Title",
	"public":true,
	"record":false,
	"broadcasting":false,
	"assets":{
		"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.

Check those thumb nails!


You May Also Like...

Erikka Innes

Developer Evangelist

Get started now

Connect your users with videos