Authenticate

video create

Video upload

Normal

medium_screen-shot-2021-01-26-at-11-48-47-am.jpg

small_screen-shot-2021-01-26-at-11-48-47-am.jpg

thumbnail_screen-shot-2021-01-26-at-11-48-47-am.jpg

screen-shot-2021-01-26-at-11-48-47-am.jpg

Erikka Innes

large_api-video-blog-tutorials.png

medium_api-video-blog-tutorials.png

small_api-video-blog-tutorials.png

thumbnail_api-video-blog-tutorials.png

api-video-blog-tutorials.png

Tutorials

Python

You've prepared the perfect ad copy for your business, but now you're trying to figure out how you can personalize the ad for each business. One great way to do that would be to use a voice over tool that allows you to customize the content based on the location of your customers. Fortunately, this is available! By combining api.video with aflorithmic.ai's voice over this problem is easy to solve. 

## Imagine, if you will, that you own a pizza chain

To make this fun, let's imagine you are the owner of a popular pizza chain - Renzo's pizza chain. You have fifty different outlets and you've prepared the perfect ad: 

--Insert video here-- 

This ad is great for one of your locations, but you want people near all of your restaurants to know they can eat the best pizza for the least dough. For each location, you'd like to run this ad, but have it play information that tells the listener the city, address, day of the week and the time of the offer being described. 

No problem! We can do this in the tutorial today. Let's get started. 

## Prerequisites 

For this project, you're going to need: 

* An api.video account - [Sign up here!](https://api.video)
* An aflorithmic.ai account - [Sign up here!](https://console.api.audio/)

## Installation

We will use the [api.video Python client](https://github.com/apivideo/python-api-client) and [Aflorithic.ai's apiaudio library](https://docs.api.audio/recipes).

Installation for api.video: 
```pip install api.video```

Installation for Aflorithmic:
```pip install -U apiaudio```

### ffmpeg installation
If you want to run the project as-is, you'll also need to install ffmpeg. These instructions help you with installation on a mac. What you'll want to do is make sure you have brew installed. Then it's very easy, you just install with:

```brew install ffmpeg``` 

You need to install ffmpeg before you install the next two items.

### pydub and pyaudio installation
pydub and pyaudio can also be difficult to install, depending on your set up and what you've tried to install already. If you made the mistake of trying to install these before installing ffmpeg, then what you would do is first run:

```brew remove portaudio```

Then, reinstall this like so: 

```brew install portaudio``` 

After these steps, you should be able to successfully install the modules you'll need. Here's the commands: 

```brew pyaudio```

and 

```brew pydub```

## Project overview 
Here's what we're going to do with the example script today:

1. Prompt to collect the api.video API key and the Aflorithmic API key. 
2. Select our video from the Videos folder (for your own tweaks later you can drop other videos here to use, or use a different folder system to organize your content). 
3. Select the script we want from the Script folder and offer the user a preview of the script to make sure it's the right one. 
4. Select the localization .csv file we want to use with our script.
5. Create a sample audio file with the voice over, using the first line from the .csv file
6. Give the user the sample file so they can make sure it sounds like what they want.
7. Next we'll combine the first audio file with the video.  
9. We'll display that file for review by the user to make sure it looks right.
10. If the user approves the file, one by one we'll create an audio file, combine it with the video, tag each video with the information from the csv, and upload it for storage and hosting on api.video.
11. We'll return the user a list of video titles and a link to a playable copy of the final file. 

## Code sample 
Here is the code sample. It's a wizard that will walk you through all the steps. The complete project is available on github here: [https://github.com/apivideo/python-api-client/blob/master/examples/video_audio/README.md](https://github.com/apivideo/python-api-client/blob/master/examples/video_audio/README.md)

## Walkthrough the important stuff
A bunch of the demo is set up to walk you through the process of combining information. We don't need to go over each while loop, but let's go over some details regarding API behavior and the tools used to create the demo. 

### The script 
You can place your script into your code directly by using quotes. It could look like this (I'm saying could because there are a few different ways to set up your api.audio script): 

You can see that the script is split into three sections. This demo doesn't really make use of the features available per section so I'm not going to go into detail for this part. Personalization is achieved by using {{ }} around the name of a column from your csv spreadsheet. They can be used in whatever order you like. 

You can also choose to read your script from a .txt file. If you choose to do this, make sure to take the quotes off from the beginning and end or it will screw up the parser. A common error you will get will say there's a problem with creating a final file or working with a URL and it's usually because something broke before that point, so keep that in mind when debugging. 

In your code, when you set up your script, you'll use a command that looks something like this: 

```script = apiaudio.Script().create(scriptText=text, scriptName=script_details[0], moduleName=script_details[1], projectName=script_details[2])
```

In this snippet, you've already authenticated with your api key (```apiaudip.api_key = your_key```) so now you can work with the api's endpoints. 

The only required field is scriptText, which will contain the text of your script. However it's useful to provide the other names for reference. Be aware that you cannot delete projects or modules. After you set up your script this way, you'll be able to reference it in your code easily via scriptId. Like so:

```script.get("scriptId")```

### The audio file
For starters, when you create an audio file with api.audio, it names your file based on your project name and personalization parameters. In this demo, if you named your project "ad" then every audio file would begin with the word "ad." Next, it puts the headers for the csv file in alphabetical order, and adds the appropriate parameter next to each header. For example, our .csv file has the columns (in this order): 

* city
* address
* day_of_week
* offer_time

After each column title, the entry that appears in the audio file will appear. To separate each column, two underscores are used. Here's a sample:

ad__address_1353%20harlem%20street__city_springfield__day_of_week_tuesday__offer_time_6%20to%208%20pm

So something you'll possibly want to do is rename the files when they arrive. An easy way to handle this is with the built-in os module. 

When creating an audio file you'll do two steps, one is text-to-speech and one is mastering the audio. For text-to-speech you can pick a voice, how fast it will speak and then give it a dictionary containing the list of personalization terms you want to insert into your script. 

You can also choose a template, which will play some background music under your spoken audio. You can see in the demo I used "copacabana." To list voices or background music options, go to the [api.audio API reference docs](https://docs.api.audio/reference) and use the endpoint for listing voices or the endpoint for listing music. 
 
### The .csv
This demo reads information from a .csv file. If you want to read from something else, you can as long as your output for your program to work with becomes a list of dictionaries. .csv is pretty simple to use, so I went with that option.

### Playing a track from your application
You can play a track to check out the audio by using a variety of tools. For this one, I used pydub and pyaudio. These are fairly popular modules. In order to use them, however, audio must be converted to .wav. You will see in the code  that two imports are made from pydub: 

```
from pydub import AudioSegment
from pydub.playback import play
```

These allow us to play straight from the terminal or wherever we may be. The code to convert to .wav and play is very straightforward:

```
wav_track = AudioSegment.from_mp3(file)
wav_track.export(audio_title, format="wav")
```

There are other choices available for converting, but api.audio returns .mp3 files, so we use the from_mp3 choice. 

After we have the track, playing it is as simple as this:

```
play(wav_track)
```

### Merging audio and video 
Prior to uploading your video to api.video, you will want to add the sound and video together. This can be accomplished with ffmpeg, which you need to import to use pydub and pyaudio anyway. The code for merging audio and video is:

```
input_video = ffmpeg.input(video)
input_audio = ffmpeg.input(wav_track)
title = title + ".mp4"
ffmpeg.concat(input_video, input_audio, v=1, a=1).output(title).run()
```

This will produce an mp4. You can then upload it to api.video. 

### Upload to api.video
For details about uploading a video with api.video, you can check out the tutorial about it here: [Upload a Video with the api.video Python Client](https://api.video/blog/tutorials/upload-a-video-with-the-api-video-python-client/)

Something to note is to upload a file, it must be in the same folder as your application or it will not upload.

Once it's uploaded, you can retrieve the .mp4 from the response and play it right away in your browser using the built-in webbrowser module. 

To retrieve the mp4 from the response, you do this:

```
link_mp4 = video_response['assets']['player']
```

And then you can open the link like this:

```
 webbrowser.open(link_mp4)
 ```

This will let you make sure everything combined properly so that the audio matches with the video the way you want. 

### Create all the localized videos
After all the steps to make sure you're creating the right type of video, you can use the recipe from api.audio with a couple of tweaks to create all your new videos with personalized ads by location, then upload them for hosting to api.video.

This demo deletes every video you upload right after the upload happens so you don't end up sitting with fifty videos in a folder.

Thanks for reading! Happy coding. :) 

Localize Advertisement Videos with Personalized Voice Overs!

api.video + aflorithmic.ai: Localize Advertisement Videos with Personalized Voice Overs!

If you'd prefer to watch this tutorial, here's a video version (without the Python client): 
                        <iframe src="https://embed.api.video/vod/vi1cigI8kYmZL5vr4cTJGch6" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>   

api.video issues a refresh token alongside an access token. You may have seen this if you've examined the json that comes back when you authenticate with your api key. It looks like this (I edited the access_token and refresh_token a lot, they're very long strings in an actual response): 

Each access token is good for one hour, then it expires. You have three ways you can deal with this ongoing expiration: 

* Delegated tokens - If you want, you can use delegated tokens for some of your work. Delegated tokens can have any expiration time you want, so you can avoid dealing with the regular expiration. Delegated tokens are only for use with uploads though. 
* Authenticate again - You can use your API key every time your access token expires, and get a new token. Or, you can use it before your access token expires. 
* Use a refresh token - A refresh token lets you get a new access token without exposing your API credentials. 

In many situations, using a refresh token will be the best option. When you authenticate, store the refresh token somewhere secure so you can use it later. Today's code sample shows you how to retrieve the refresh token, then use it to get a new token. 

And that's it! You can continue developing, or continue services in your system that need a new token to complete tasks. 

If your token expires, hit refresh and protect your API key

small_jozsef-hocza-keys-unsplash.jpg

thumbnail_jozsef-hocza-keys-unsplash.jpg

jozsef-hocza-keys-unsplash.jpg

When your token expires, hit refresh and protect your API key

Delegated Upload

If you have a large video you need to upload, sometimes the server you're uploading to will not accept it in one request. Different servers have different limits. For api.video, you can upload a video file up to a size of 199 MiB before your file is considered too big. Once your video crosses this limit, to upload it you'll need to break it into chunks and send it that way. You send each chunk and the server reassembles it for you. 

In this tutorial, we'll walk through a simple example of how to do a large video upload.

<center><iframe src="https://giphy.com/embed/jVeI3SzbxKGKQ" width="480" height="480" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/vhs-vcr-jVeI3SzbxKGKQ">This looks like it would turn into a really big video file.</a></p><br></center>

## Prerequisites
* [Account](https://dashboard.api.video) with api.video 
* api.video API key 
* You'll need access to Python and you'll need to install the requests library if you don't already have it added

And if you'd rather watch this tutorial than read it, check out our video tutorial here: 
                        <iframe src="https://embed.api.video/vod/vi3oTmhrZdwpAdJiEjeIQ7Fz" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>
                    

## What You'll Be Doing 
This is a quick summary of what you're going to do to upload your large video. 

1. You'll authenticate with api.video using your API key and retrieve a token that lasts one hour that you can use to access all of api.video's other endpoints.
2. You'll create a video container for your video and retrieve the videoId. 
3. You'll use the videoId to create the endpoint you'll send your video to.
4. You'll break up your video file into chunks, then upload each chunk of the video file.

## Troubleshooting / What to Watch Out For 
If you decide to build your own uploader, a few things will help you out: 

* Remember that you must open the file as binary and work with it as binary. It's easy to forget and open it without adding 'rb' or depending on what you're doing, 'wb'.
* Headers are very important. The wrong header will prevent you from sending your content. 
* When using the Content-Range header, you must make sure you are listing the correct set of bytes being sent. If you are off by even one byte, it won't work. You will get weird errors like: 
```UnicodeDecodeError: 'utf-8' codec can't decode byte 0xd1 in position 52: invalid continuation byte``` And the solution is often a simple fix - correct how you're listing your bytes in the header.
* When you send bytes in the Content-Range header, it's inclusive. If you want to send the first 100 bytes, you write it as 0-99. This can get confusing when you're breaking your file into chunks because you can say 'grab the first 100 bytes' and the computer knows to grab 0-99. When you say 'grab the next 100 bytes,' the computer would grab 100-199. However, it's easy to write a dynamic header where you make mistakes like listing 0-100 instead of 0-99, or starting over on the same byte, for example 0-100, then 100-200. All these kinds of mistakes will cause a decode or encoding error. If you choose to build your own uploader instead of using this sample, keep this in mind. 
* If you label what type of file you're sending, you may cause unexpected issues. This sample works by opening, reading, and sending your video file as chunks of binary data. When it arrives, it's encoded into HLS for you, no matter what kind of video it started out as. 

## Code Sample 

```
## How to upload a large video that is over 199 MiB to api.video. (Though this script will also work for videos under 200 MiB if you want to test it out.)

import requests
import os 

## Set up variables for endpoints (we will create the third URL programmatically later)
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"

## Set up headers and payload for first authentication request
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}

## Send the first authentication request to get a token. The token can be used for one hour with the rest of the API endpoints.
response = requests.request("POST", auth_url, json=payload, headers=headers)
response = response.json()
token = response.get("access_token")

## Set up headers for authentication - the rest of the endpoints use Bearer authentication.

auth_string = "Bearer " + token

headers2 = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create the video container payload, you can add more parameters if you like, check out the docs at https://docs.api.video
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload test."
}

## Send the request to create the container, and retrieve the videoId from the response.
response = requests.request("POST", create_url, json=payload2, headers=headers2)
response = response.json()
videoId = response["videoId"]

## Create endpoint to upload video to - you have to add the videoId into the URL
upload_url = create_url + "/" + videoId + "/source"

## Set up the chunk size. This is how much you want to read from the file every time you grab a new chunk of your file to read.
## If you're doing a big upload, the recommendation is 50 - 80 MB (50000000-80000000 bytes). It's listed at 6MB (6000000 bytes) because 
## then you can try this sample code with a small file just to see how it will work.  The minimum size for a chunk is 5 MB.

CHUNK_SIZE = 6000000

## This is our chunk reader. This is what gets the next chunk of data ready to send.
def read_in_chunks(file_object, CHUNK_SIZE):
    while True:
        data = file_object.read(CHUNK_SIZE)
        if not data:
            break
        yield data

## Upload your file by breaking it into chunks and sending each piece 
def upload(file, url):
    content_name = str(file)
    content_path = os.path.abspath(file)
    content_size = os.stat(content_path).st_size

    print(content_name, content_path, content_size)

    f = open(content_path, "rb")

    index = 0
    offset = 0
    headers = {}

    for chunk in read_in_chunks(f, CHUNK_SIZE):
        offset = index + len(chunk)
        headers['Content-Range'] = 'bytes %s-%s/%s' % (index, offset -1, content_size)
        headers['Authorization'] = auth_string
        index = offset
        try:

            file = {"file": chunk}
            r = requests.post(url, files=file, headers=headers)
            print(r.json())
            print("r: %s, Content-Range: %s" % (r, headers['Content-Range']))
        except Exception as e:
            print(e)

## Add a path to the file you want to upload, and away we go! 
upload('your-giant-file-here.mp4', upload_url)
```

## Code Walkthrough

Wanna know how it works in a little more detail? Great, here we go! The first couple of sections might look like some of the other blog posts, scroll down for a discussion about the new stuff if that's the case. 

You'll start by adding the requests and os libraries, so you can easily make HTTP requests.

```
import requests
import os
```

Next, let's assign a variable to each endpoint we'll use, they'll be a little easier to work with. We're going to assign two of them here, and we'll use the second one later to build the third one: 
* [Authentication](https://docs.api.video/reference/basic-authentication) endpoint - This is where we send our API key to exchange it for a token. It's **auth_url** in the code sample.
* [Videos](https://docs.api.video/reference/api/Videos#create-a-video-object) endpoint - Specifically we'll use the feature on this endpoint that's for creating a video. It's **create_url** in the code sample.
* [Video Upload](https://docs.api.video/reference/api/Videos#upload-a-video) endpoint - It looks a lot like the other endpoint. It's create_url + "/videoId" + "/source". We'll construct this after we get a videoId to work with. 

```
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"
```

### Authentication - Get Your Token
We'll prepare our headers and payload for authentication, then send a POST request to api.video. With the api.video API you start authentication by sending a request using your API key to retrieve a token. You can use your sandbox or your production key, the backend will figure out which you are using and handle it accordingly. If you choose to use your sandbox credentials for this walkthrough, your video will be uploaded with the watermark 'FOR DEVELOPMENT PURPOSES ONLY.': 

```
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}
response = requests.request("POST", auth_url, json=payload, headers=headers)
```

Now we need to get the token from our response, so we can authenticate with the rest of api.video's endpoints when we want to do something. To get the token, we'll convert the response to JSON, then retrieve the token out of the JSON dictionary. 

```
response = response.json()
token = response["access_token"]
```

### Set up a Video Container 
Using the token, we'll get the headers and payload ready for our next request, which will be to ask api.video to create a video container for us.

```
## Set up headers for authentication
headers_bearer = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create a video container
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload of Big Buck Bunny to demo how to do an upload from a folder on your computer."
}
```

api.video endpoints use bearer authentication. Add the authorization header for bearer authentication to your list of headers, and then for the payload we keep it simple, just a title and description. But what about the path to your file? Don't worry we're just creating a container right now. When you upload from your computer, you create a container first, and do your upload second. 

### Send Your Request and Grab the VideoId
For the next part of our walkthrough, we'll send our request, convert the response to JSON, and retrieve the videoId. We need the videoId so we can tell api.video what container we want to upload our video to. 

```
response = requests.request("POST", create_url, json=payload2, headers=headers_bearer)
response = response.json()
videoId = response["videoId"]
```

### Create the Endpoint for Uploading Your Video
Set up the endpoint you'll upload your video to, which is composed of "https://ws.api.video/videos" + "/" + videoId + "/source". 

### Build a Data Chunk Reader
To break your data into chunks, you're going to want to decide how big each chunk should be, and then from an open file keep grabbing the next chunk of data to read. We'll set the chunk size at 1000000 bytes. This is fairly small, in case you wanted to try the sample with a smaller video file to see how it works. If you plan to start using this data chunk reader, make the chunk size larger. A good size is about 50-80 MB or about 50000000-80000000 bytes. 

This function assumes you've already opened your file elsewhere, and it's using **yield**. What this does, is return a generator. Every time you use this function as part of a for loop, it will run until it hits yield, then return the value. Yield 'remembers' where you left off, so each time you loop through, it will return a new chunk of data. 

```
CHUNK_SIZE = 1000000

def read_in_chunks(file_object, CHUNK_SIZE):
    while True:
        data = file_object.read(CHUNK_SIZE)
        if not data:
            break
        yield data
```

### Start Your Large Video Upload 
<center><iframe src="https://giphy.com/embed/TI3IErToEDAERYK7LL" width="480" height="480" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/TalentSmiths-loading-talentsmiths-janetsmiths-TI3IErToEDAERYK7LL"></a></p><br></center>
Here's our next function. This one is the upload function, and it contains our chunk reader. What we do here, is use the os library to grab some file details, so we know how big the file we're going to send is, the path to get to it, and the name of the file. 

We open our file, and NOTE...we are opening our file in binary. This is important to remember, since opening a video file in other formats will probably not work. 

Next we set up our index, that's going to represent what point we're at in the file. We also set up the offset, which represents how far forward to move the index after we send each chunk. 

Then we start reading chunks of data. For each chunk of data, we prepare the Content-Range header so we are correctly listing what part of the file we are sending in bytes. To send our data chunk, we need to put it into a one item file dictionary. We do that, and then for readability assign it to a variable. Then we send our request! This will loop through until we're out of data chunks (the last chunk will probably be smaller than the others). 

```
def upload(file, url):
    content_name = str(file)
    content_path = os.path.abspath(file)
    content_size = os.stat(content_path).st_size

    print(content_name, content_path, content_size)

    f = open(content_path, "rb")

    index = 0
    offset = 0
    headers = {}

    for chunk in read_in_chunks(f, CHUNK_SIZE):
        offset = index + len(chunk)
        headers['Content-Range'] = 'bytes %s-%s/%s' % (index, offset -1, content_size)
        headers['Authorization'] = auth_string
        index = offset
        try:

            file = {"file": chunk}
            r = requests.post(url, files=file, headers=headers)
            print(r.json())
            print("r: %s, Content-Range: %s" % (r, headers['Content-Range']))
        except Exception as e:
            print(e)
```

You don't need any other headers. 

You will know you are successful after you send the last chunk. It's possible to receive a -200- response for each chunk, then have it not work out at the very end, so make sure to watch your video upload the first time through. Success is denoted by the response to the last chunk, where you will receive something that looks like this: 

```
{
 'videoId': 'viyourvideoIdz', 
 'title': 'Demo Vid from my Computer', 
 'description': 'Video upload test.', 
 'public': True, 
 'panoramic': False, 
 'mp4Support': True, 
 'publishedAt': '2021-02-08T06:14:53+00:00', 
 'createdAt': '2021-02-08T06:14:53+00:00', 
 'updatedAt': '2021-02-08T06:14:53+00:00', 
 'tags': [], 
 'metadata': [], 
 'source': {
	 'type': 'upload', 
	 'uri': '/videos/vviyourvideoIdz/source'
	 }, 
 'assets': {
	 'iframe': '<iframe src="https://embed.api.video/vod/viyourvideoIdz" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>', 
	 'player': 'https://embed.api.video/vod/viyourvideoIdz', 
	 'hls': 'https://cdn.api.video/vod/viyourvideoIdz/hls/manifest.m3u8',    
	 'thumbnail': 'https://cdn.api.video/vod/viyourvideoIdz/thumbnail.jpg'
	 }
}
r: <Response [201]>, Content-Range: bytes 4000000-4824145/4824146
```

Check your video's status in [your dashboard](https://dashboard.api.video/). If you have a very large video file, wait a few minutes while api.video finishes processing it. When processing is finished, you'll be able to see a thumbnail for your video and play it from the dashboard. 

If your video upload is unsuccessful, you won't receive the detailed message listed above. You might receive an additional 200 response, or a 400 response for each chunk, depending on how much went wrong with your upload. 
In the dashboard, you may see your video uploaded, but it stays stuck on processing. If this happens, review your code, or contact us with your issue in the [community forum](https://community.api.video/). 



Upload a big video file using Python

small_BigFileWithPython.png

thumbnail_BigFileWithPython.png

Big-File-With-Python.png

If you have some videos on your computer that you need to upload to api.video, you're in luck - today's tutorial will show you how to do just that using Python. Your video must be under 200 MiB to use this method. The code sample is available on github in the [api.video python-examples repository](https://github.com/apivideo/python-examples). Let's get started! 

medium_pexels-designecologist-1779487.jpg

small_pexels-designecologist-1779487.jpg

thumbnail_pexels-designecologist-1779487.jpg

pexels-designecologist-1779487.jpg

## Prerequisites
* An [api.video account](https://dashboard.api.video/register) 
* api.video API key 
* You'll need access to Python and you'll need to install the requests library if you don't already have it added

## What You'll Be Doing
This is a quick summary of what you're going to do to upload your video. 

1. You'll authenticate with api.video using your API key and retrieve a token that lasts one hour that you can use to access all of api.video's other endpoints.
2. You'll create a video container for your video and retrieve the videoId. 
3. You'll use the videoId to upload your video from your computer to api.video. You can only upload a video to the videoId once. If you decide you wanted to upload a different video, you'll have to go through the create container and upload video steps again. You don't need to repeat the part where you get a new token unless your token expires (so if you take an hour long break and come back, you'll need to redo that step then). 

## Code Sample 

```
## How to upload a video under 200 MiB using the api.video API

import requests

## Set up variables for endpoints
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"

headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}

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

auth_string = "Bearer " + token


## Set up headers for authentication
headers_bearer = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create a video container
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload of Big Buck Bunny to demo how to do an upload from a folder on your computer."
}

response = requests.request("POST", create_url, json=payload2, headers=headers_bearer)
response = response.json()
videoId = response["videoId"]

## Create endpoint to upload video to
upload_url = upload_url + "/" + videoId + "/source"

## Create upload video headers 
headers_upload = {
    "Accept": "application/vnd.api.video+json",
    "Authorization": auth_string
}

file = {"file": open("local/path/to/myvideo.flv", "rb")}
response = requests.request("POST", upload_url, files=file, headers=headers_upload)
json_response = response.json()
print(json_response)
```

## Code Walkthrough

You'll start by adding the requests library, so you can easily make HTTP requests.

<center><iframe src="https://giphy.com/embed/YGlRW1Am9q7e0" width="320" height="480" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/books-libraries-shelves-YGlRW1Am9q7e0">How people added libraries before computers did it for you.</a></p><br></center>

```
import requests
```

Next, let's assign a variable to each endpoint we'll use, they'll be a little easier to work with. We're going to assign two of them here, and we'll use the second one later to build the third one: 
* [Authentication](https://docs.api.video/reference/basic-authentication) endpoint - This is where we send our API key to exchange it for a token. It's **auth_url** in the code sample.
* [Videos](https://docs.api.video/reference/api/Videos#create-a-video-object) endpoint - Specifically we'll use the feature on this endpoint that's for creating a video. It's **create_url** in the code sample.
* [Video Upload](https://docs.api.video/reference/api/Videos#upload-a-video) endpoint - It looks a lot like the other endpoint. It's create_url + "/videoId" + "/source". We'll construct this after we get a videoId to work with. 

```
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"
```

### Authentication - Get Your Token
We'll prepare our headers and payload for authentication, then send a POST request to api.video. With the api.video API you start authentication by sending a request using your API key to retrieve a token. You can use your sandbox or your production key, the backend will figure out which you are using and handle it accordingly. If you choose to use your sandbox credentials for this walkthrough, your video will be uploaded with the watermark 'FOR DEVELOPMENT PURPOSES ONLY.': 

```
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}
response = requests.request("POST", auth_url, json=payload, headers=headers)
```

Now we need to get the token from our response, so we can authenticate with the rest of api.video's endpoints when we want to do something. To get the token, we'll convert the response to JSON, then retrieve the token out of the JSON dictionary. 

```
response = response.json()
token = response.get("access_token")
```

### Set up a Video Container 
Using the token, we'll get the headers and payload ready for our next request, which will be to ask api.video to create a video container for us.

```
## Set up headers for authentication
headers_bearer = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Create a video container
payload2 = {
    "title": "Demo Vid from my Computer",
    "description": "Video upload of Big Buck Bunny to demo how to do an upload from a folder on your computer."
}
```

api.video endpoints use bearer authentication. Add the authorization header for bearer authentication to your list of headers, and then for the payload we keep it simple, just a title and description. But what about the path to your file? Don't worry we're just creating a container right now. When you upload from your computer, you create a container first, and do your upload second. 

### Send Your Request and Grab the VideoId
For the next part of our walkthrough, we'll send our request, convert the response to JSON, and retrieve the videoId. We need the videoId so we can tell api.video what container we want to upload our video to. 

```
response = requests.request("POST", create_url, json=payload2, headers=headers_bearer)
response = response.json()
videoId = response["videoId"]
```

### Create the Endpoint for Uploading Your Video
Set up the endpoint you'll upload your video to, which is composed of "https://ws.api.video/videos" + "/" + videoId + "/source". You also need to add the headers. For Python, you don't want to use the "Content-Type": "multipart/form-data" header you see listed if you try the API explorer. Because you are doing an upload with only one part, it won't work. Omit this in your headers. Set things up like this: 

```
headers_upload = {
    "Accept": "application/vnd.api.video+json",
    "Authorization": auth_string
}
```

For the payload, you're sending a video file, so you'll have to open the file, attach it to a dictionary, and for readability, we assign the dictionary to a variable. We use "rb" because we want to open the file as read-only binary format. Check it out: 

```
file = {"file": open("sample-flv-file.flv", "rb")}
```

We can assign our variable in our request to upload our video, and then process and print the request response:

```
response = requests.request("POST", upload_url, files=file, headers=headers_upload)
json_response = response.json()
print(json_response)
```

The response provides a lot of detail about your video:

```
{
	'videoId': 'video ID here', 
	'title': 'Demo Vid from my Computer', 
	'description': 'Video Upload From My Computer', 
	'public': True, 
	'panoramic': False, 
	'mp4Support': True, 
	'publishedAt': '2021-02-05T04:25:02+00:00', 
	'createdAt': '2021-02-05T04:25:02+00:00', 
	'updatedAt': '2021-02-05T04:25:02+00:00', 
	'tags': [], 
	'metadata': [], 
	'source': {
		'type': 'upload', 
		'uri': '/videos/video_ID_here/source'
	 }, 
	'assets': {
		'iframe': '<iframe src="https://embed.api.video/vod/video_ID_here" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>', 
		'player': 'https://embed.api.video/vod/video_ID_here', 
		'hls': 'https://cdn.api.video/vod/video_ID_here/hls/manifest.m3u8',
		'thumbnail': 'https://cdn.api.video/vod/video_ID_here/thumbnail.jpg'
 }
}
```

* **videoId** - the unique identifier for your new video. Before it was just referencing a container, now it's referencing a container that holds your video!
* **title** - the title you provided for your video when you made the container
* **description** - a description of what the video contains
* **public** - by default, your video is public 
* **panoramic** - by default, your video isn't listed as being a 360° (panoramic is the term api.video uses for 360° or immersive video)
* **mp4Support** - whether you have an mp4 version of your video available or not. By default you do. If you turn this off, your video will not be downloadable from a player and there won't be a link to an mp4 version of your file.
* **publishedAt** - the time your video was published, in ISO-8601 format.
* **createdAt** - the time your video was created, in ISO-8601 format.
* **updatedAt** - the time your video was updated in ISO-8601 format.
* **tags** - you can add individual key words to categorize your videos and make them easier to search if you have a lot of them.
* **metadata** - you can add a dictionary of key value pairs that categorize your videos for searches.
* **source** - this lists the video type, which is upload, and the link you add to the api endpoint to get to your video. 
* **assets** - this is a list of links you can use to set up different services with your video. You can embed an iframe using the iframe code, use the player link to add the file to a player, get the manifest file if you need the source for live streaming, and api.video selects a thumbnail for you automatically. 

You can update all of this information should you choose to. That's it for uploading a video from your computer using Python! 

If you have any questions or suggestions, please share them on our [community forum](https://community.api.video/) and if you still haven't created your api.video account, you can do that [here](https://dashboard.api.video/register). Happy building! 

Upload a video with api.video’s API (Python)

Photo by <a href="https://www.pexels.com/photo/silver-imac-displaying-collage-photos-1779487/">Designecologist</a> from Pexels

Upload a video from your computer with the api.video API (Python)

If Python is your programming language of choice, and you want to quickly upload a video to api.video using a public URL, you've come to the right place. The code sample is available on github in the [api.video python-examples repository](https://github.com/apivideo/python-examples). Let's get started! 

<center><iframe src="https://giphy.com/embed/l0IyjiXOXTX6Yemsg" width="480" height="270" frameBorder="0" class="giphy-embed" allowFullScreen></iframe><p><a href="https://giphy.com/gifs/l0IyjiXOXTX6Yemsg"></a></p><br></center>

## Prerequisites

If you would prefer to watch a video that explains the same information as this tutorial, you can watch this:

* [An api.video account](https://dashboard.api.video/register)
* api.video API key 
* URL for a public video you want to try uploading (we'll be using this link here: [https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File](https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File))
* You'll need access to Python and you'll need to install the requests library if you don't already have it added

You can also review the API reference documentation for uploading videos here: [Upload a video](https://docs.api.video/reference/api/Videos#upload-a-video)

## Code Sample

```
import requests

## Set up variables for endpoints
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"

## Set up header for first authentication request
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "sandbox or production key here"
}

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

auth_string = "Bearer " + token


## Set up headers for bearer authentication
headers2 = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}

## Upload the video
payload = {
    "title": "My Demo Video",
    "source": "https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File"
}
response = requests.request("POST", create_url, json=payload, headers=headers2)

## Check out the response
print(response.json())

```

## Code Walkthrough
This section walks through the code to give you an idea of what you'll be doing.

### Set up Authentication with Your API Key
You'll start by adding the requests library, so you can easily make HTTP requests.

```
import requests
```

Next, let's assign a variable to each endpoint we'll use, they'll be a little easier to work with. We're going to use two endpoints today: 
* [Authentication](https://docs.api.video/reference/basic-authentication) endpoint - This is where we send our API key to exchange it for a token. It's **auth_url** in the code sample.
* [Videos](https://docs.api.video/reference/api/Videos#create-a-video-object) endpoint - Specifically we'll use the feature on this endpoint that's for creating a video. It's **create_url** in the code sample.

```
auth_url = "https://ws.api.video/auth/api-key"
create_url = "https://ws.api.video/videos"
```

Create the payload for your headers and the payload for your payload. These are for your authentication request. The api.video API requires that you authenticate with your API key to obtain a token. Your token is good for one hour and can be used to authenticate with all other endpoints. 

NOTE: You can use your sandbox or your production key. The backend for api.video will figure out which you selected and route your request appropriately. If you didn't pay for a full account, all of your videos will be watermarked 'FOR DEVELOPMENT PURPOSES ONLY'.

```
headers = {
    "Accept": "application/json",
    "Content-Type": "application/json"
}

payload = {
    "apiKey": "your API key here"
}

```

Send a request with your header and payload information, convert the response to json so you can retrieve information from it, and then grab **access_token**.

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

Now you have your token, you need to set new headers that are for Bearer authentication. Create a string with your token for the new Authorization header, and a new header payload. 

```
auth_string = "Bearer " + token

headers2 = {
    "Accept": "application/json",
    "Content-Type": "application/json",
    "Authorization": auth_string
}
```

### Send Your Video Upload Request

And the part you've been waiting for, the code for video upload! By default, your video is public and includes mp4 support, which is a link to a 1080p mp4 of your file. If you want to change these settings so your video is private or mp4 support is turned off (this will make it so no one can download your video from a player) you can [check our docs](https://docs.api.video/reference/api/Videos#create-a-video-object) for details about all the parameters your payload can include. For now, we'll keep the payload simple: 

```
payload = {
    "title": "My Demo Video",
    "source": "https://www.learningcontainer.com/mp4-sample-video-files-download/#Sample_AVI_File"
}
response = requests.request("POST", create_url, json=payload, headers=headers2)
print(response.json())
```

You can use this payload to see the sample run. For your own upload, you may want to use a different title and a different source link.

### Review Video Details in the Response

When you print the response here, you get back a lot of interesting information about your video: 

```
{'videoId': 'vi8PXlHuWN25wPOVtGfBSQkJ', 
'title': 'My Demo Video', 
'description': '', 
'public': True, 
'panoramic': False, 
'mp4Support': True, 
'publishedAt': '2021-02-04T01:50:23+00:00', 
'createdAt': '2021-02-04T01:50:23+00:00', 
'updatedAt': '2021-02-04T01:50:23+00:00', 
'tags': [], 
'metadata': [], 
'source': {
	'type': 'upload', 
	'uri': '/videos/vi8PXlHuWN25wPOVtGfBSQkJ/source'
	}, 
'assets': {
	'iframe': '<iframe src="https://embed.api.video/vod/vi7EVlHuWN05wPOVtGfBSQkJ" width="100%" height="100%" frameborder="0" scrolling="no" allowfullscreen="true"></iframe>', 
	'player': 'https://embed.api.video/vod/vi8PXlHuWN25wPOVtGfBSQkJ', 
	'hls':'https://cdn.api.video/vod/vi8PXlHuWN25wPOVtGfBSQkJ/hls/manifest.m3u8',   'thumbnail': 'https://cdn.api.video/vod/vi8PXlHuWN25wPOVtGfBSQkJ/thumbnail.jpg'
  }
}
```

* **videoId** - a unique ID that identifies your uploaded video
* **title** - the title of your video
* **description** - if you put a description of your video it appears here
* **public** - whether your video is public or not
* **panoramic** - whether your video is 360° or not
* **mp4Support** - whether your video has an mp4 version of it available or not (turn this off if you don't want people to be able to download your video from a player)
* **publishedAt** - when you first published your uploaded video
* **createdAt** - when your uploaded video was created
* **updatedAt** - when you last updated your video
* **tags** - if you added individual tags to categorize your video with, they appear here
* **metadata** - if you added key value pairs to categorize your videos with, they appear here
* **source** - details about your video source 
* **assets** - different ways you can upload or work with your new video, there's a link you can use with a player, the source file for the hls versio of your video, and a thumbnail that's selected for you (you can change it if you like, but that's a different tutorial)

And that's how you do a simple video upload to api.video! Let us know if you have any questions in [our Community](https://community.api.video/)! Happy building!

Upload a video to api.video using a public URL

large_upload-a-video-to-api-video-using-a-public-url.png

medium_upload-a-video-to-api-video-using-a-public-url.png

small_upload-a-video-to-api-video-using-a-public-url.png

thumbnail_upload-a-video-to-api-video-using-a-public-url.png

upload-a-video-to-api-video-using-a-public-url.png

Video delete

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

We hate to see it happen, but sometimes a video becomes out of date - the information is no longer correct. Even though you can remove the link, sometimes it is just better to pull it off the web entirely. In this tutorial, we'll walk through the steps to delete a video from your api.video account.

## Authentication

To delete a video from your api.video account, you'll need to [authenticate a session](https://api.video/blog/tutorials/authentication-tutorial/) with your apiKey.  
```
curl -X POST \
https://ws.api.video/auth/api-key \
-H 'Content-Type: application/json' \
-d '{"apiKey": "your_api_key"}'

```

This will return your authorization token for future API requests.

## Deleting


All api.video videos are identified by a videoId.  If you know the videoId of the video you are deleting, you can now begin the deletion process.

> Hint:  The videoId is the random string at the end of the link you use for the video on the web.

Now we simply call the [delete video](https://docs.api.video/reference/api/Videos#delete-a-video-object) endpoint with the videoId in the URL, and the authorization token as a header.

```
curl --request DELETE --url https://ws.api.video/videos/vi3bO7H9UAzibjwF5QxwJcw5  --header 'accept: application/vnd.api.video+json'  --header 'authorization: Bearer {api_token}'
```

This request will delete the video vi3bO7H9UAzibjwF5QxwJcw5.  The api will simply return a 204 response on successful deletion.

## Try it out!

We've built a sample Node application at [delete.a.video](https://delete.a.video). This API selects 3 videos from an api.video account.  This is done with the search video attribute, and will returm the 3 oldest videos called "Live Stream". These three videos are displayed on the page, and by clicking the delete button - you can remove them permanently from the account!

The sample code for the app is on [Github](https://github.com/dougsillars/deleteVideoDemo) if you'd like to use the NodeJS SDK to delete videos.

Questions of comments?  Leave a post on the [community forum](https://community.api.video).

Video deletion: how to delete a video from your account

large_1024px-thebigredbutton-3085157011.jpg

medium_1024px-thebigredbutton-3085157011.jpg

small_1024px-thebigredbutton-3085157011.jpg

thumbnail_1024px-thebigredbutton-3085157011.jpg

1024px-thebigredbutton-3085157011.jpg

Video deletion: Learn how to delete a video from your account

At api.video, we offer a number of ways to upload video into your account. When you [create and upload a video](https://api.video/blog/tutorials/video-upload-tutorial/), the first step is to authenticate with your API, and generate an authentication token.

For a static website, it may not be feasible to create a new token on each page load. For instances like these, we offer a delegated upload token. This token works like a public key to your api.video account, allowing secure uploads without exposing your API key.

## Create an [api.video](https://api.video) account

If you already have an account, you can skip this step.

Before you can start uploading your first video, you need to **[create an api.video account](https://dashboard.api.video/register)**.

Once you are logged in to the Dashboard, select the environment of your choice (sandbox or production) and copy your API key.

large_Screenshot 2024-02-21 at 4.55.04 PM.png

medium_Screenshot 2024-02-21 at 4.55.04 PM.png

small_Screenshot 2024-02-21 at 4.55.04 PM.png

thumbnail_Screenshot 2024-02-21 at 4.55.04 PM.png

copy-api-key-through-dashboard.png

You'll be able to find your API key in the dashboard **[dashboard.api.video](https://dashboard.api.video/overview)**.

There are separate API keys for Sandbox and Production **[environment](https://docs.api.video/reference#environments)**.

In production, you can also manage multiple API keys from your dashboard, for different applications.

## Generate the Upload Token

We will use the [delegated upload API](https://docs.api.video/reference/api/Upload-Tokens#generate-an-upload-token) in order to generate our token. In this example, we will use curl to make the requests, however, you will find examples and code snippets with various programming languages using [api.video API client libraries](https://docs.api.video/sdks/api-clients) in our [documentation](https://docs.api.video/vod/delegated-upload-tokens).

This will result in JSON response with the delegated access token:

`{"token":"to1R5LOYV0091XN3GQva27OS"}`

This token can now be used to upload videos into your api.video account. In the example below, I am uploading a video of clouds into my sandbox account.

Go ahead and try this yourself!  Since the delegated upload is into my sandbox account, the video will be watermarked and deleted after 72 hours. Simply point the ```-F file@``` to a video on your local file system, and it will be uploaded into my sandbox.

You'll receive a response similar to this:


my_cool_video.mp4

These urls can be shared for others to watch your video. On opening the player link, you might see a video like this: (Note the video link in the JSON above has expired and will throw a 404 error).

## Expiring Delegated tokens

Delegated tokens act like a public API - anyone with this token and the api.video url could upload videos into your account. For this reason, you can [revoke](https://docs.api.video/reference/api/Upload-Tokens#delete-an-upload-token) delegated tokens so they can no longer be used.

## Delegated Token Time To Live

In addition to expiration, you can also set a 'time to live' (TTL) when creating a token. Once the token expires, itc an no longer accept uploads.  If you generate the token when the uplaod begins - you must ensure that at least one segment of the video is uploaded before the token expires, or the video will be rejected at the server.  You can split the video with the [JavaScript file API](https://api.video/blog/tutorials/uploading-large-files-with-javascript/).  Once the token expires, you'll have 24 hours to complete the rest of the upload (which should be PLENTY of time).

## HTML 
The [API docs](https://docs.api.video/reference/api/Videos#upload-a-video) have a thorough explanation on how to build a form and upload a video.

## Conclusion

Delegated upload offers a user-friendly method for video uploads, allowing the creation of tokens with specified expiration. This method is ideal for one-time video uploader solutions and quick content uploads without immediate metadata concerns.

Let us know how you are using delegated upload in your video service in our [community forum](https://community.api.video/)


Delegated uploads: Make video uploads with a created token

medium_delegatedupload.jpg

small_delegatedupload.jpg

thumbnail_delegatedupload.jpg

delegated-video-upload.jpg

Delegated uploads: Make video uploads with a token you create

live - create

Live streaming your content is a great way to connect with your audience. In this tutorial, we'll walk through the steps you need to follow to set up a video livestream.

Note: we have example code of setting up a live stream in the [browser](https://api.video/blog/tutorials/live-stream-tutorial/), with [Zoom](https://api.video/blog/video-trends/start-remote-work-with-online-video-and-zoom-us/)
and with [OBS](https://api.video/blog/video-trends/video-live-streaming-in-just-5-easy-steps/).

[Here](https://docs.api.video/reference/api/Live-Streams#create-live-stream) is the direct link to the technical docs to create a live stream.

In order to establish a video livestream, you must first create a livestream container at api.video. Then you can begin streaming with the tool of your choice. In this example, the live stream will be created with OBS, free and open source software for video streaming.  

## Creating Live Stream

### Step 1: Authenticate

You need an access_token in order to create and upload a video.

You will need your API key to obtain the access_token. You can find your API key in [your dashoard](https://dashboard.api.video).  

This tutorial uses the sandbox endpoint. To upload your video in production, simply replace all `sandbox.api.video` instances with `ws.api.video`.

First, call the authentication endpoint and get your access token.


#### Example - Curl Request


### Step 2: Create the Live Stream

Now we [create the live stream](https://docs.api.video/reference/api/Live-Streams#create-live-stream). In the JSON parameter, feel free to edit the name of the live stream from "Your Stream Name" to whatever you want to name your stream.

#### Example - Curl Request

Your Stream Name

Now the server is ready to accept our live stream, and once broadcast begins (JSON above shows broadcasting:false), it will be viewable on the urls listed in the JSON response.

### Connecting Live Video

The JSON response above lists your live stream's streamKey, which will be needed in OBS to connect your video to the server.

in the OBS application:

1. Esablish a source.  In the sources section, choose a video feed to share.  You could choose to share your screen, or to share your camera (on a Mac: Video Capture Device, and then in the "Device" dropdown choose the camera).  You should now see the video source in the main OBS window.
2. Connect OBS to api.video. Under Settings, choose Stream.  You'll see a choice for service - choose custom.
3. The server should be `rtmp://broadcast.api.video/s` and the `streamKey` is the value you received in the Json when you created the stream. Click OK to accept the changes.
4. Press Start Streaming.
5. Share the embed, iFrame, so that others can watch your stream!


Extra Step:  The default video poster that your users will see is api.video branded.  You can update the thumbnail with an image of your choice:

## Conclusion

That's all it takes. We've walked through the process of creating a livestream at [api.video](https://api.video), and then how to connect that video's streamKey into OBS. Using OBS, we are then able to broadcast video to all our viewers, who can watch using the player (oriframe) url provided by the api.

[Give it a try](https://dashboard.api.video/register), and let us know how it worked for you in our [community forum](https://community.api.video). We're also there to help out if you run into any difficulties.

Create a Live Stream

large_create-a-live-stream.png

medium_create-a-live-stream.png

small_create-a-live-stream.png

thumbnail_create-a-live-stream.png

create-a-live-stream.png

Every call made to an api.video API requires an access_token. This tutorial will walk you through the authentication steps.

> NOTE: All of the SDKs abstract out the need for authentication.

You will need your API key to obtain the access_token. You can find your API key in [your Dashboard](https://dashboard.api.video/login).

This tutorial uses the sandbox endpoint. To upload your video in production, simply replace all ```sandbox.api.video``` instances with ```ws.api.video```.

First, call the authentication endpoint and get your access token.

**Example - Curl Request**

**Example - Http Request**
```
POST /auth/api-key HTTP/1.1
Host: sandbox.api.video
Content-Type: application/json
{
	"apiKey": "your_api_key"
}
```

**Example Response:**

The response has the access token and a refresh token. The "expires_in" parameter tells you that the token is valid for 3600 seconds = 1 hour.

## Conclusion

That's all there is to it!  Grab your api_key from [your dashboard](https://dashboard.api.video/login) and give it a try. If you run into any issues, feel free to reach out on our [forum](https://community.api.video), and we'll gladly help out!

Authentication steps

curl

api.video can help you simplify your video hosting and [delivery](https://api.video/product/live-stream/). As such, one of the first things you'll want to do is to upload videos and get them loaded into the service. Once you upload the video, we'll take care of transcoding the video into streams for delivery to your users.

The easiest way to upload videos into api.video is using our API, and we'll walk through the steps to use the API and get your video online in this tutorial.

## Using cURL

This tutorial uses curl and HTTP requests to authenticate your session, create a video, and then upload the video. 

This example works for smaller videos, but as your video gets larger, you will want to break the video into smaller bites (bytes?) to facilitate upload.  Here's how do to that using the [command line](https://api.video/blog/tutorials/video-upload-tutorial-large-videos/). 

### Other languages?

We have many tutorials on video upload.  Here are a few links to help you:

* [JavaScript](https://api.video/blog/tutorials/uploading-large-files-with-javascript/).
* [Python](https://api.video/blog/tutorials/upload-a-video-from-your-computer-with-the-api-video-api-python/)
* [PHP](https://api.video/blog/tutorials/helpful-php-scripts-pt-2-upload-videos-from-an-ftp-server/)

We have several [Clients](https://docs.api.video/) for additional platforms that will help you get started uploading videos quickly.

You can also check out the API reference documentation for uploading a video here: 
* [Create a video](https://docs.api.video/reference/api/Videos#create-a-video-object)
* [Upload a video](https://docs.api.video/reference/api/Videos#upload-a-video)

### Step 1
You need an access_token in order to create and upload a video.

You will need your API key to obtain the access_token. You can find your API key on [your dashboard](https://dashboard.api.video/overview).

This tutorial uses the sandbox endpoint. To upload your video in production, simply replace all ```sandbox.api.video``` instances with ```ws.api.video```.

First, call the authentication endpoint and get your access token.

**Example - Curl Request**

### Step 2
We will use the create video API to create and upload the video.

The ```Authorization: Bearer``` header uses the access_token from the first step. Hint: Make sure to not remove the end ' when pasting in your token.
The ```title``` parameter is required, so you must add a name to your video.
If your video is hosted on a server, you can use ```"source":"url"``` in the JSON to add the video.
If your video is on your local machine, we'll need to do one additional step.

This example also includes the video description.
The response contains links to the video location, and generates a unique identifier ```videoId```.

**Curl Request**

This is a title

### Step 3: Upload the video file.

> In this step, we use the upload endpoint of the API.  You can also use [delegated tokens](https://docs.api.video/reference/api/Videos) for the upload. The advantage of delegated tokens is that these are safe to use on a webpage (whereas your authorisation token is not), and the videos are directly uploaded to api.video.  You can learn more about using [delegated tokens](https://api.video/blog/product-updates/video-access-management-how-to-create-deliver-and-manage-private-videos-and-what/) for this same experience.

In Step 2, we saw how to link to a video already hosted. If the video is not hosted, and must be uploaded, we will call the video upload API:

When the upload is complete, a JSON response similar to that of step 2 is returned.

That's it - if you access the assets links in the response JSON - you can begin sharing the video you just created. Note: The mp4 URL is only added to the API response once the mp4 video has been encoded, which may take a few additional seconds.

## Conclusion

In this post, we learned about authentication of our account with our [api.video](https://api.video) token, creating a video container, and uploading a video into that container. Once your video is uploaded, it is ready to be shared with your audience!

If you have any questions or suggestions, please share them on our [commmunity forum](https://community.api.video/). To start building now, singup for an api.video account [here](https://dashboard.api.video/register). Thanks for reading! 

Video upload with cURL

codec

small_cedric.webp

thumbnail_cedric.webp

cedric.webp

Cédric Montet

Product updates

At api.video, our goal is for video to be easy and affordable for anyone to build, be it individuals or organizations. We understand that achieving this goal means reducing costs at some stage of the video streaming process. That’s why, we now offer adaptive bitrate encoding for your videos at zero cost. 

&nbsp;

Yes, you heard me right. 

&nbsp;

**Encoding videos will be absolutely free for all video qualities (1080p or 4K) at [api.video](https://api.video/) - no hidden calculations, footer notes or tricks.**

(Check out this [video](https://www.youtube.com/watch?v=ouosgLbW7Ts) for more details) 


## A step towards making video streaming affordable

Video encoding is crucial as it makes it possible for videos to be shared and played smoothly on the internet. It is why we are easily able to consume various types of video media, whether it’s a YouTube video, our favorite shows on Netflix, or even catching up with friends across the globe on Zoom. Video encoding basically makes the world go around in regards to anything related to video and video content.

&nbsp;

We at api.video recognize that. From [increasing the transcoding and playback speed ](https://api.video/blog/product-updates/2021-in-review/)to building [specialized hardware like ASICs](https://api.video/blog/video-trends/the-comeback-of-specialized-hardware/) cards to increase our transcoding capacities, we've been working to make video streaming easier for you every day. And after dedicating ample time to engaging with our customers and learning about their concerns, free encoding seemed to be the next step in this direction. 

&nbsp;

So, we worked tirelessly behind the scenes to give you what no one else will - free encoding for all video qualities, be it 360p or 4K. 

## How does free video encoding benefit you as a customer

The benefit is straightforward: you save a LOT of money!

&nbsp;

- With free video encoding, you will have one less thing to worry about. As you know, you pay for three things for streaming videos — encoding, hosting, and delivery – out of which encoding is the most expensive, especially if you have a lot of videos. Free video encoding will allow you to focus your attention and resources to what is most important.

&nbsp;

- As the video needs of your app users grow, you might need to scale up your encoding capacity. Free video encoding services will give you the power to scale without any additional costs, meaning your users can handle more videos without increasing your expenses.

&nbsp;

- You can [migrate from your previous provider to api.video](https://api.video/compare/azure-media-services/) without paying an ‘entry tax’ to us. With free video encoding, you no longer need to spend money on encoding videos with a new provider when you have already paid for encoding with an older one.

&nbsp;

Now with all the saved cost, you can allocate your resources and money to a place where it is actually important – building your product and delighting your users. 

## How to get started

To use the free video encoding benefit, getting started is easy. 

&nbsp;

- If you’re a new user, [sign-up](https://dashboard.api.video/register) for a free sandbox account and start uploading your videos
- If you are looking to migrate from another vendor, [import](https://import.api.video/) your videos from your current vendor
- If you have any questions, [talk to us](https://meetings.hubspot.com/apivideo/talk-to-us) by booking a slot in our calendar

&nbsp;

To know more about our[ features](https://api.video/features/), [pricing](https://api.video/pricing/) or ask any other questions, [talk to our team ](https://meetings.hubspot.com/apivideo/talk-to-us)and we will help you out. 

&nbsp;

Or, you can straightaway [sign-up](https://dashboard.api.video/register) for a free sandbox account and check our product out for yourself. 


Huge pricing update: Introducing video encoding at no cost

small_Blog_Zero Cost.webp

thumbnail_Blog_Zero Cost.webp

Blog_Zero Cost.webp

api.video

Video trends

Modern technology has been helpful for an increasingly fast and simple method of consuming various types of video media, whether it’s a YouTube video, our favorite shows on Netflix, or even catching up with friends across the globe on Zoom. Despite the relative ease of doing anything related to video, a few complex processes take place behind the scenes, away from public view. One such process is video encoding.

Video encoding basically makes the world go around in regards to anything related to video and video content. Thanks to the technologies behind the video encoding process, it has become much easier for people and companies to share video content on the internet. But what exactly is video encoding, and what happens during the process? We’ll take a closer look at this and much more in this handy guide to video encoding.

## What is video encoding?

In a nutshell, video encoding occurs when you take raw video footage, either from a digital camera or an analog film camera, and digitally compress it to make it a more manageable file size. Video encoding happens daily in both professional and personal capacities, and many people don’t realize it.

But, without encoding, services like Netflix and YouTube would not exist – or, at least, not in the same way that it does today. Without it, we couldn’t send videos of our beloved pets to our friends and family as easily as we can today.

## Why is video encoding used?

There are a variety of reasons why video encoding is used, but all factors point to the single function of video encoding – **compression**.

This is done to ensure optimal performance and compatibility with a selected suite of software and hardware, be it for DVD/Blu-ray playback, mobile viewing, online video streaming, or general video editing. A file's video and audio information undergo transformation and compression during the encoding process, all in accordance with the requirements of the selected encoding standard.

On a professional level, the ability to compress raw video into more manageable sizes makes it easier to transmit video content such as training, promotion, presentation, and so on over the internet. 

On a personal level, video encoding makes it much easier to send videos taken from your phone directly to friends and family. Most modern-day personal devices have built-in video encoding capabilities to allow for this to happen without a second thought.

To put things in perspective, uncompressed or unencoded video can have a data rate that’s as low as 3,000 Mbps and as high as 12,000 Mbps, depending on the length and quality of the video recorded. 

**Without encoding, it would take up to days for anyone to not just transmit video, but to be able to consume it, too.**

## Differences between video encoding and video transcoding

You need to be familiar with two more [essential terms related to video encoding](https://api.video/what-is/) – transcoding and codecs.

Transcoding relates to the conversion from one digital encoding format to another. It takes the already encoded video file, decompresses it, and then alters it before re-encoding or compressing it into a different codec. Codecs are what allow encoding to occur in the first place. They are software or hardware that gives us the ability to compress video to make them more easily stored and delivered tightly.

While you may hear “encoding” and “transcoding” used interchangeably, the two terms actually mean different things. Putting it succinctly, encoding is the initial process of compressing a video from a source – such as a camera – into a codec, while transcoding takes an already encoded video file to convert it into a different codec.

## Examples of video codecs

In order to understand video encoding, you must first be familiar with two interrelated terms: [video codecs and video formats](https://api.video/blog/product-updates/every-video-format-codec-and-container-explained/). These also tend to be used interchangeably, but much like the terms encoding and transcoding, they refer to two different things.

Video formats are the type of files in which the compressed video/audio is stored. Also known as a “container”, you can tell what a video format is by looking at the file’s extension — the three to four characters that sit after a period in a file name. Here are some of the most common video formats used today:

* MP4
* FLV
* MOV
* MKV
* LXF
* MXF
* AVI
* WebM
* QT

On the other hand, **the codec is short for “Coder / Decoder” (compression / decompression)** and relates to the video compression algorithms that allow encoding to happen. Over the years, codecs have gone through multiple iterations as it coincides with the increasing sophistication and rise in the quality of filmmaking. 

If you’re a content creator, you might be aware of some of the video codecs that exist today:

- **H.264 – also known as AVC, this is the most widely-used video codec available on every platform and mobile device.**
- H.265 – also known as HEVC, stands for High-Efficiency Video Coding, and it’s slowly overtaking H.264 as the standard. This codec can compress video much more efficiently than its predecessor.
- **VP9 – is an open-source, royalty-free codec developed by Google and is considered the direct competitor of H.265. The video compression codec VP9 was created to reduce file sizes, making streaming videos simpler.**
- **AV1 – is another royalty-free, open-source codec released in 2019 by the non-profit Alliance for Open Media. It was developed to become the successor to Google’s VP9 and contend with HEVC more directly.**

## How do different technologies handle video encoding

As you may have suspected, there are a majority of ways that different technologies handle the video encoding process. Let’s take a look at the most common technologies that use video and how video encoding works on each of them:

### Video editing software

When it comes to video content creation, a majority of people will use one of two video editing software — Adobe Premiere Pro or Apple’s Final Cut Pro. Both of these video editing software handle video encoding in very similar ways: when exporting the finished video.

Depending on which device the video content is recorded on, it will already be encoded and formatted according to the settings of the device. For those using iPhones recording 1080p video at 25 frames per second (FPS), for example, the iPhone will automatically encode the video using H.264 and contain it in a .mov file format. The video editing software will “open up” the container to get to the encoded, compressed video file within so the editing process can begin.

After editing the footage is complete, it will need to be exported, which typically concerns video encoding. The edited raw media taken from a recording device such as a camera will be encoded via the codec of the person’s choosing before being put into a .mp4 container once they’ve hit “export”. As we’ve mentioned before, the most common codec used in video content creation is H.264 for HD videos, with 4K videos using H.265. 

### Websites

Different websites utilize different techniques to handle video encoding – with a majority of the major sites like YouTube, Netflix, and so on using their own technologies to handle the process. A majority of social media websites allow you to upload video files directly onto the site to share, although most of them require the files to be saved in specific containers. 

These websites will take your video file and transcode it before using their own systems and serves to re-encode it to match multiple display resolutions. This process will happen regardless of your video file's original codec and settings. Different websites have different processes, but companies that don’t have the capacity to build their own video encoding systems can use a third-party application programming interface (or API) to handle this process. These APIs act as [dedicated video encoder](https://api.video/what-is/video-encoding/) that allows companies to add on-demand videos to their websites more efficiently.

Using [api.video](https://api.video) as an example, all of the videos submitted to the platform will be transformed into H.264 codec in an MP4 container. This may be done using transmuxing and/or transcoding.

We expect the video bitrate to be lower than 16 Mbps for up to 1080p resolution and 50 Mbps for up to 4K resolution. We accept any bitrates, however, we will scale them down to the limits mentioned because anything above is usually challenging for most viewers’ connection to watch.

### API

The ability to generate, store, and distribute video is made possible via a video API. [api.video](https://api.video)’s solution can be tailored to suit any specific need. 

The backend process of video on demand (VOD) is exceptionally complex, even if you’re a software programmer specializing in video. It is necessary to encode, package, and typically transcode the data before sending it to any of several possible destinations. All of these things, and more, may be done with minimal fuss using api.video.

Our API basically keeps the complexities of streaming media hidden from view, so you can rapidly develop apps with as much control as you need. This saves time and effort so developers can concentrate on making the product.

## Conclusion

As you can see through this video encoding guide, a lot of work goes into making the video you watch and the video you share possible. Without video encoding compressing raw video footage, it could take days to upload and transmit video content over the internet and perhaps even longer to be able to download and enjoy them. 

The best part about encoding at api.video is that is offered at ZERO cost. You will only be charged for delivery and hosting of your videos, and the encoding will be free. Now integrate your videos in minutes with api.video or [contact us](https://api.video/contact/) for more information.

A Guide to Video Encoding & Video Codecs

large_poster-3.png

medium_poster-3.png

small_poster-3.png

thumbnail_poster-3.png

poster-3.png

Encoding and transcoding are often used interchangeably but they have slightly different definitions. **Encoding is the initial process of converting raw video files into a specific digital format or codec.** It involves compressing and packaging the video data, often to reduce file size while maintaining acceptable quality. Encoding prepares the video for storage, transmission, or playback.

&nbsp;

**Transcoding, on the other hand, involves converting a video from one digital format or codec to another.** This is typically done to optimize the video for different devices or platforms, adapt to varying network conditions, or ensure compatibility with specific playback requirements. Transcoding occurs after encoding and often involves changing resolution, bitrates, or formats without altering the content itself.

## What goes on behind encoding a video?

It's easy to say that encoding is when you go from an _uncompressed source_ to a _compressed source_, but you may ask, what exactly do compressed and uncompressed sources mean?

&nbsp;

Uncompressed sources are video files that contain data that comes directly from a camera sensor vs. encoded video. In the digital space, it's SDI (Serial Digital Interface) or HDMI (High Definition Multimedia Interface). Both of them are popular standards. You'll find HDMI in places like your GoPro camera, or a mini camcorder. These days, you might also find HDMI in professional settings, but SDI is more common due to its reliability. Another example of an uncompressed source would be something analog, for instance, VHS tapes.

&nbsp;

A compressed sources, on the other hand, are video files that have undergone compression during the encoding process. Compression involves reducing the file size by removing unnecessary information or encoding the data in a more efficient format. This process results in a smaller file size, making it more manageable for storage, transmission, and playback.


## What are the types of transcoding methods?

There are three types of transcoding, depending on what you are trying to do to get a video to suit a particular browser, player, or platform:

* **Lossless-to-lossless** - This type of transcoding maintains the quality of your video across formats but allows you to take advantage of better hardware or compression algorithms. 
* **Lossless-to-lossy** - This type of transcoding will decrease your video in quality, but it will benefit you in ways such as – you will get a smaller and/or faster playing file, or a file that is compatible with the requirements of a particular platform, player, or browser.
* **Lossy-to-lossless** - Sometimes people think this means they are regaining quality. This isn't the case in this type of transcoding. If you transcode from a lossy format to a lossless format, all that it means is that you will not lose additional quality in the conversion process. You will not regain data you already lost through compression.

## Codecs for encoding and transcoding

For both encoding and transcoding, you will need to make use of codecs. A codec's job is to compress and decompress video files. It's right there in the name -  **co**mpress **dec**ompress or encode decode. So basically, codec is an algorithm that takes the video and shrinks it or changes it into a format that makes it compatible with the requirements of wherever you want the video to play. There are many codecs because there are many ways to compress a video or livestream for playback.



## What is transmuxing?

Now that you know the difference between encoding and transcoding, let's throw one more term in there - transmuxing. Transmuxing is when you change the container for a video instead of the format. It's a way of repackaging a video to make it compatible somewhere without changing what's in the file. 

&nbsp;

This process is faster than encoding or transcoding and takes less computing power because you only change the container, not the file. It's great when you need to quickly make something available, but the downside is that it doesn't handle things like making multiple video resolutions available. If you choose a container type that's incompatible with your video file, you may also cause compatibility issues, resulting in not being able to play the video.

## In closing

* **Encoding** - Encoding happens when you compress a raw data file from a video camera sensor or an analog source like a VHS tape. 
* **Transcoding** - Transcoding happens when you take an already compressed video file and change it to another format.
* **Transmuxing** - Transmuxing happens when you change the container of a video file but leave the video file untouched. 

We hope that explains the difference between encoding and transcoding clearly. 

_If you are looking for an affordable video API solution that does not burn a hole in your pocket for transcoding and encoding videos, check out our offerings on our [homepage](https://api.video/) or [sign-up for a free account here](https://dashboard.api.video/register)!_

Encoding and transcoding: what's the difference? 

large_EncodingTranscoding.png

medium_EncodingTranscoding.png

small_EncodingTranscoding.png

thumbnail_EncodingTranscoding.png

EncodingTranscoding.png

Once I upload my video, how quickly will it be ready to be viewed?

Our reply to this question has always been “it's really fast.”  And it is really fast. But, the dev team gave me access to the backend database, and pointed me to a few tables that might be helpful (thanks to Thomas Persohn for your patient help!)

Thus armed, I waded into a sea of data to better understand how fast our videos are encoded at api.video

## Encoding

When a video is uploaded to api.video, it is re-encoded to a HLS stream, with several different video dimensions and bitrates.  This allows api.video to deliver properly sized video to all users - no matter the device or network connection. (Read our post on [Responsive video delivery](https://api.video/blog/video-trends/responsive-video-delivery/) to learn more.)

> Summary:  All videos are encoded at 240p, 360p, 480p, 720p, 1080p and 2160p. However, the videos are only encoded up to the initial size of the video (so if the original video is 720p, there will not be 1080p or 2160p versions available). 

**FYI:** For our customers, encoding is absolutely free – we offer adaptive bitrate encoding at zero cost. 

How long does this step take? If a customer uploads a video to our service - they want to know how efficient api.video creates the content for viewing.

### Data in the study

We are constantly making adjustments to our infrastructure to speed the encoding step of our video (and that is one reason this post is dated 2H 2020 - we expect to be faster in early 2021). The last major adjustment was made in mid October, so the data presented in this study from every video uploaded to the api.video service between 15 October and 2 December 2020.

### Parameters that affect encoding

There are 2 major parameters that affect the speed of encoding a new video stream: the output dimensions and the length (duration) of the video.  

#### Dimensions

The output video dimensions have a huge impact on video creation - a 3840 × 2160 (or 4K or 2160p) video has millions more pixels than a 320x240 (240p) video, so it takes a lot longer to create.  In general, the videos exit the encoding process from smallest to largest.

#### Duration

If a video is 30 frames per second, and is 60 seconds long, there are 1800 frames to be created.  If a 30 frame per second video is an hour long 3600s), there are 108,000 frames to be created, so the longer the video - the more time for creation.

## Analysis

To better understand the encoding time, I divided the data by the size of the output video size, and looked at 2 lengths of video  - those under 5 minutes, and videos that are 45-75 minutes long (we are often asked how long a 1 hour video takes to encode).

I calculated encoding time for each bucket of video using percentiles.  

> Quick review - percentiles break the data into 100 evenly sized segments, so the 25th percentile is when 25% of the videos have been encoded. The median is the 50th percentile, and is when 50% of videos have been encoded.  We report here to the 95th percentile for video encoding.

### Short videos - under 5 minutes long

Many of the videos uploaded to api.video are short - under 5 minutes long.  These videos are generally ready to play in a few seconds:



The above chart has a lot of data, the 25, 50, 75, 90 and 95th percentile encoding times for all 6 variants of the video that api.video creates.

The median video is ready to play (at 240p) in 5.6 seconds, but a 720p version will be ready in 15s after encoding begins, and the 4K version will be ready in 37 seconds.

95% of all videos (under 5 minutes) will be playable in 32.6s, and will have 1080p versions ready in just over 2 minutes (140s).

### Long videos - 45 - 75 minutes long

Our most frequently asked question on encoding is "how long for a 1 hour video to be encoded and ready?"  Here are the numbers:


Observant viewers will see there are no 4K videos in this report. At this time, there are very few 4K streams that reach the 1 hour timeframe, and the data was quite noisy.  Hopefully, more of our 'long uploads' will add 4K support, so we can add this metric in our next update.

The median hour long video (red line) will be ready to play (at 240p) in just over 9 minutes (555s), and a 720p version will be ready about 18 minutes after encoding begins (1099s).

95% of hour long videos will have a 240p version ready in 33 minutes, and 720p in 54 (3230s).  the 1080p version will be available for 95% of videos in 108 minutes,

## Conclusion

Short videos will be ready to play - even at high resolution - in under a minute: the median 4K encoding for a short video is 37s. 

Hour long videos take longer to encode, and the median 720p video will be ready in 18 minutes.  95% of 720p videos will be ready to play in 54 minutes.

This is really fast! You can have responsive streaming video ready for your customers in just a few minutes with a simple upload!

That said, our team is working hard in the background to improve our infrastructure to make our encoding speeds even faster! 

We're really excited to have hard numbers to share with you on our encoding speeds, and we cannot wait to re-benchmark this data in 2021 to see how much faster your videos will be encoded as we improve our service.

Do you have questions about api.video or video encoding? Reach out on our [community page](https://community.api.video).


How fast does api.video encode video? 2H 2020 data

medium_gif.jpg

small_gif.jpg

thumbnail_gif.jpg

gif.jpg

Huge pricing update! Introducing video encoding at zero cost

Featured article

# api.video blog

Blog

Follow the api.video Blog to explore tutorials, video use cases, and learn about on-demand and live-streaming video updates.

Video on demand

Live streaming

Analytics

Video infrastructure

Video player

See all features

Online learning

Short-form videos

Marketplace & E-commerce

Video messaging and recording

Quickstart guides

Documentation

Ecosystem catalog

Clients & SDKs

Community

Blog

Demos

Help center

Authenticate