API client

Private Videos

Normal

small_t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

thumbnail_t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

t02cw29ka-u04jtt0jcg3-549047173ac2-512.jpeg

Artem Matinian

large_api-video-blog-product-updates.png

medium_api-video-blog-product-updates.png

small_api-video-blog-product-updates.png

thumbnail_api-video-blog-product-updates.png

api-video-blog-product-updates.png

Product updates

NodeJS

The internet is fascinating; vast information zooms through back and forth, enabling millions of people worldwide to share their knowledge and experiences. However, it’s also a place where one must be cautious and protect oneself regarding private content and limit access to personal information, especially videos. We understand that it’s a sensitive topic for many it's difficult to implement on your own, so we created Private Videos.

## Secure & manage access to your videos

Maybe you are asking yourself: “ok, but how does *video privacy setting* help me?”. There are quite a few use cases for private videos, and we’ve discussed the hassle of securing the videos yourself. 

- On-demand videos behind a paywall
- Content Protection
- Video NFTs
- Video for internal use only
- Private video messaging
- Disposable one-time videos

And pretty much any video where you want to limit or restrict access! 🔒

### What are private videos

A private video is a video object secured by a private token and can be consumed only once. After the private token is consumed, the video is only available once you have another private token assigned to it. So, even if your user has the video URL, sharing it with anyone else is useless. 

We tried to make it as simple as possible to secure your videos:

- Create a video container with a `public: false` flag, which will make the video (surprise 🥳) private!
- Private videos will generate a new private token each time a request is made for that video id.
- Each private token is usable only once.

If you like to get into nitty gritty details, feel free to check out our docs about [Private Videos](https://docs.api.video/delivery-analytics/video-privacy-access-management).

### How to deliver private videos to your audience

After you learn how private video works and what it’s good for, we can now talk about the delivery part, which is the most important part. 

To reiterate the private video concept, here’s a visual representation of how the whole thing works:

large_private-videos-1.png

medium_private-videos-1.png

small_private-videos-1.png

thumbnail_private-videos-1.png

private-videos-1.png

Knowing that now we can finally start building stuff! 

It’s that simple! (if you want the advanced stuff, scroll down to “Time to roll up our sleeves!”)

Let’s try to deliver one video in HTML with our own (amazing!) [api.video](https://api.video) player. 

Suppose you already have a cool video uploaded. Go to the dashboard and get make the video private (if it’s not already private)

Now that the video is private, we can deliver it to users. Here’s a quick snippet in HTML that you can use to play your video in the browser. Just copy the code snippet and replace the URL with your private video URL. You can find the video URLs in the Assets section of the Video Details:

large_screenshot-2023-02-09-at-20-41-37.png

medium_screenshot-2023-02-09-at-20-41-37.png

small_screenshot-2023-02-09-at-20-41-37.png

thumbnail_screenshot-2023-02-09-at-20-41-37.png

video-urls-assets-section.png

We played the video once with a browser. Now, open another browser tab in incognito mode and play the same video. You can see that it’s gone! no more video! don’t worry; even though the video still exists, the token changes once you consume it. If you refresh the video details page, you’ll notice that the private token has changed. If you paste the URL with the new private token in the `src` you will be able to play the video again in a new tab, but already with a different private token. Cool right? 🙂

### Let’s get programmable

The concept works the same for API requests. You can request the API and fetch the video by id; if it’s a private video the response will give you the URLs with the private tokens (the `XYZ` in the URLs stands for the private token):

test video

### Assets? what assets? 🏠

Notice that JSON above has a field called `assets`. We’ll refer to assets later, but it’s important to know what they are. Assets include the URLs for the video thumbnail, iframe with the [api.video](https://api.video) player for embedding directly into the HTML, and several other video formats like `mp4` and `hls`. Now you know! 💡

### How to create a sample app with private videos

Now that we know the privacy setting concepts, it’s time to write some example apps that will give us a small glimpse into what powerful tool we are dealing with here.  

Let’s assume that we want to build an app that will display all the private video thumbnails on our website and make them clickable so it will open a video once it’s clicked. Something like that:

On the backend, we will have to do some magic. While with public videos it’s pretty simple as just returning the videos, for private videos we will need to get the session first. Let’s look at the HTML code:

large_screenshot-2023-02-10-at-19-43-18.png

medium_screenshot-2023-02-10-at-19-43-18.png

small_screenshot-2023-02-10-at-19-43-18.png

thumbnail_screenshot-2023-02-10-at-19-43-18.png

private-video-html-code.png

Notice the `avh` parameter in the query string? The `avh` parameter is where you will pass the session token... oh wait, what's a session token?!

### Session token & session management

Session Tokens are designed to retain the same session for a user. Let’s take an example - a user opened a tab with the private video and would like to refresh the tab, or the video didn’t work with our player for whatever reason. Hence, you redirect the user to an mp4 version of that video (different asset). For these cases, we’ve created the session tokens.

There are two types of tokens for private videos:

- **Private token** (which we already discussed): generated every time you pull a private video from the API.
- **Session token**: This token is used to retain the private video session with the same private token.

At a very high level, to request different assets for the same private video, more than having the private token is required; you also need to retain the session. For that, we have the session token. In the flowchart below, you can see that for each private video, we are using a session token + the private token:

large_private-videos-post-15feb23.png

medium_private-videos-post-15feb23.png

small_private-videos-post-15feb23.png

thumbnail_private-videos-post-15feb23.png

private-videos-post-15feb23.png

So let’s get a bit technical here. To start the session, you will need to request the `/session` endpoint, get the session token, add it to the first asset you request, and then add it to every following asset you request. In the example above, we will request the `/session` endpoint, then add the session token to the query string of the private video thumbnail → request an embedded video asset with the session token in the query string → request a private video asset in mp4 format with the session token, and so on, you got the idea 😄

In other words:

Get the session token:
`GET https://vod.api.video/vod/{videoId}/token/{private token}/session`

Response:
`{"session_token": "111-222-333"}`

Now we can request the private video thumbnail asset → embedded video → mp4:

`GET https://vod.api.video/vod/{video id}/token/{private token}/thumbnail.jpg?avh={session token}`

`GET https://embed.api.video/vod/{video id}?token={private token}&avh={session token}`

`GET https://vod.api.video/vod/{video id}/token/{private token}/mp4/source.mp4?avh={session token}`

Sample runnable code of the above app in Node.js:

Let’s do a step-by-step review of what we are doing here.

1. We are creating a server that will serve HTML on port 3000 with Node.js
2. To make it easy on ourselves, we create a wrapper that will make an HTTP request to [api.video](https://api.video) with api key already embedded in HTTP header. That’s the `apiVideoReq` function.
3. We will get a raw response from the apiVideoReq, so need to create a parser that will parse the JSON response if the request is successful (200). That’s going to be the `getJsonResponse` 
4. Then we need to create a function that will get the list of our videos. That’s pretty simple with the wrapper function we have, so let’s reuse the `apiVideoReq` and make a request to `[https://ws.api.video/videos](https://ws.api.video/videos)` endpoint. You can find more info about the `/videos` endpoint [here](https://docs.api.video/reference/api/Videos#list-all-video-objects).
The response we'll get is an array of objects of the following format:

Notice that the second object has a property `public` which is set to `false` , which means that the video is private; hence we need to get all of these videos. 

1. Extract all the private videos from the list by creating an iterator that will run through the array of objects and get each video with the flag `public` set to `false` pushing only the assets and video id into a new array.
2. If you remember, we need to get the session token by requesting the /session endpoint. The endpoint accepts the video id and private token; however, if you notice the private token is only in the URL. So let’s extract it! we can use this simple regex to extract it from the embedded URL `(?<=token=).*$` 
3. We first extract the private token from the URL and map it to the asset objects (with the video URL, video id, etc.) 
4. Then we request the /session endpoint passing in the video id and private token, and we get the session_token. Now we can also map to the same asset object.
5. We’re almost done; hang in there! now let’s get generate `<img>` tags with the src as the asset thumbnails and add the session token in the query string as an `avh` parameter, i.e: `<img src=https://vod.api.video/vod/AABBCC/token/c77d7bf3-4e2f-4a85-9e15-5c35992c11fc/thumbnail.jpg?avh={{session token}}>` .  Then in the same line generate the `<a href>` tag that will lead us to the actual video, and as you understood already, it too has to include the session token, i.e: `<a href=https://embed.api.video/vod/AABBCC?token=c77d7bf3-4e2f-4a85-9e15-5c35992c11fc&avh={{session token}}>`
6. And lastly, generate the HTML `<head>` and `<body>` while encapsulating the `<a href><img></a>` we’ve already created, and…. DONE!

Now you have clickable thumbnails of your private videos which you can secure behind user credentials for example 🙂

Let’s summarize what we’ve learned here:

- We’ve understood how private videos work and the purpose of private videos with real-life use cases.
- We’ve also built a small app to leverage private videos to create clickable thumbnails with minimal code.

If you have any questions or feedback about this article, do not hesitate to contact our support. You can also find the docs for private videos [here](https://docs.api.video/delivery-analytics/video-privacy-access-management).

Create, deliver, and manage private videos

large_14feb23-copie-2.png

medium_14feb23-copie-2.png

small_14feb23-copie-2.png

thumbnail_14feb23-copie-2.png

video-access-management.png

Video Access Management: How to create, deliver, and manage private videos and what are they anyway?

Android

Mobile

Player

Player update

thumbnail_thibault_rond.png

thibault_rond.png

Thibault Beyou

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

Kotlin

We have now released an [api.video](https://api.video/) player for Android. The api.video player helps you to include your videos in your Android applications very easily and quickly. In this tutorial, we are going to show how to add an api.video player to your Android application. It will only take 5 minutes. Let’s do this! 👊

Before starting this tutorial, you can upload a video to your api.video. If you haven’t yet, you can check [Upload your first video guide](https://docs.api.video/vod/upload-a-video-regular-upload), which will walk you through your first video upload. The video that you have uploaded to your api.video account will have an assigned `videoId`. In the following steps, we will call for your videoId using the `YOUR_VIDEO_ID` parameter.

To just give you a quick preview, we are going to create an Android application with an api.video player that looks like this:

## The api.video player for Android

The api.video Android player is available on GitHub and comes with an example application, and the artifact is hosted on Maven Central.

The minimum Android API version supported by the api.video Android player is 24. Make sure that you don’t have a `minSdk` version under 24.

The API is divided into 2 main components:

- **The player view:** This component displays the video and its controls: `ApiVideoExoPlayerView` class.
- **The player controller:** This component controls the video and its events: `ApiVideoPlayerController` class.

## Add api.video Android player to your project

If you don’t have an Android application yet, you need to create one before you go further. The [Build Your First Android App in Java](https://developer.android.com/codelabs/build-your-first-android-app#0) is a simple guide that will help you create your Android application. 

### Dependency

The first thing is to add the [api.video](https://api.video/) Android player to your project dependencies. In your application `build.gradle`, add your `dependencies` tag as shown below:

It’s always good to check out if a [new version](https://github.com/apivideo/api.video-android-player/releases) is available.

To have access to the view, I am going to use `ViewBinding` in this tutorial because it is elegant to use as it will be more user-friendly. Now we add the `android` tag:

### XML Layout

In your `Activity` layout, add a player view:

You might have some constraints to add depending on the parent layout.

With `ViewBinding`, we can access our `ApiVideoExoPlayerView` by using the following field:

### Implementation

The main part of the implementation is to create a player controller, but it depends on several other components.

To manipulate video from api.video, the `videoId` is wrapped in an object called `VideoOptions`:

Create a player controller in your `Activity`. For example, in the `onResume`:

Launch the application. You have successfully integrated the [api.video](https://api.video) Android player in your application! 🥳🥳🥳

### Video privacy setting

For more information on changing video privacy settings, see this [article](https://api.video/blog/product-updates/video-access-management-how-to-create-deliver-and-manage-private-videos-and-what/).

If your application requires the use of private videos, then pass your private token to the `VideoOptions`:

### Fullscreen

For the fullscreen button, you will have to develop the fullscreen behavior. The base principles are: 

* When full screen is activated, hide all surrounding views, menu,…, and lock the application in landscape mode.
* When the full screen is deactivated, display surrounding views and unlock the application orientation.

These behaviors must be implemented on the `onFullScreenModeChanged` of `ApiVideoExoPlayerView.Listener`:

In this quick tutorial, you learned about how to simply add an [api.video](https://api.video) player for your Android application. Now you know how to add the api.video player as a dependency, configure the XML layout, and implement the player controller. Moreover, you learned how to change your video privacy and how to set up a fullscreen behavior. 

You can successfully integrate the api.video Android player in your own application by following the steps in this tutorial. For an example of api.video Android player, see the [example](https://github.com/apivideo/api.video-android-player/tree/main/example) provided in the player repository.

If you miss any features, face any bugs, or come across any other issues, we will be happy to help you on our [GitHub issues](https://github.com/apivideo/api.video-android-player/issues) page.🤝

How to add an api.video player to your Android application

large_23nov22-1.png

medium_23nov22-1.png

small_23nov22-1.png

thumbnail_23nov22-1.png

How-to-add-api-video-player-to-your-android-app.png

Delegated Upload

video create

doug.jpg

twitter-brands.svg

Doug Twitter

Doug Sillars

Where I live in the UK, there are miles and miles of footpaths - publically accessible trails that cross private property.  There's an expectation that those that use the public footpaths will respect the land/plants/crops of the private owners, in exchange for access to the beautiful countryside.

## Public access to api.video

api.video has a concept of [delegated tokens](https://api.video/blog/tutorials/delegated-uploads) which works like a public key - granting anyone with the key access to upload videos into your account. Now, much like the public footpaths, the usage of the public key is expected to be reasonable, and not overused.

But...it is the internet. While most of the users will behave and use the delegated upload appropriately, there might be a bad egg or two that cause issues. To help mitigate public token upload abuse, we have added [revocation](https://docs.api.video/reference/api/Upload-Tokens#delete-an-upload-token) of delegated tokens. We also have added a 'time to live' where you can provide an expiration time (in seconds) to your token.

So we've wrapped some security around the major vector to delegated token abuse. Even with this change, we have not alleviated all the questions from our customers who are grappling with ideas of privacy with a public token.  In this post, we'll show how to address the most common concerns we've heard from our users. 






## Public, but Private

*"Can I have a 'one use' delegated token?*

This is a fabulous idea - it completely removes the issue of delegated token abuse - the token "self destructs" upon video upload.



thumbnail_single-use.jpeg

single-use.jpeg

*"Can I make a delegated upload private by default?"*


A [private video](https://api.video/blog/tutorials/tutorial-private-videos) has a unique token in the url that allows **one view** of the video.  Each time the video is served, a new URL must be requested from api.video. This prevents the general public from seeing the video, and allows you to decide on the access.  By default, all videos are public.

Sometimes, as we walk the footpaths, we come across a path that is marked as private - the landowner does not want the public in that area.  

Setting a public, delegated token to private videos is like the "No Trespassing sign" on the footpath.

medium_notrespassingbydjuradjvujcic.jpg

small_notrespassingbydjuradjvujcic.jpg

thumbnail_notrespassingbydjuradjvujcic.jpg

notrespassingbydjuradjvujcic.jpg



*"Can I disable mp4 download link by default?"*

By default, the ```mp4Support``` parameter is set to ```true```, allowing the download of a private video.  By setting this to false, you can prevent the download from occurring.  Another "keep out" sign on the public path, if you will.


medium_forbidden.jpg

small_forbidden.jpg

thumbnail_forbidden.jpg

forbidden.jpg

 
### Private access, but with the public token??

Can we make the video private and disable the mp4 *while* using the public delegated token?  You can!  

Can we create a single-use delegated token - one per video upload?  Yes, we can (to a degree).  But I think this approach is close enought to a unique upload token to be secure and protect your account from bad actors on the internet.


## Demo Time

We've created a demo showing a public/private upload.  You can try it out yourself at [privatelyupload.a.video](https://privatelyupload.a.video/).


When you visit this page, you see a form for video upload.  I am writing this post in mid-December, so will use a trailer from a classic Christmas movie in my upload:

online form for video upload. We'll be uploading the Die Hard trailer.

large_screenshot-2020-12-17-at-15-46-49.png

medium_screenshot-2020-12-17-at-15-46-49.png

small_screenshot-2020-12-17-at-15-46-49.png

thumbnail_screenshot-2020-12-17-at-15-46-49.png

screenshot-2020-12-17-at-15-46-49.png

When I begin the upload (by selecting the video), I create an XMLHTTPRequest to the server with the video name, description, and if the video should be public/private, support/not support mp4:

### Set video privacy

This request is sent to the "createVideo" endpoint on my server.  The Node server extracts the JSON from the body, and creates a video container at api.video.  When we create the container, we can set the privacy settings for the video to be uploaded - namely if it should support mp4 download, and if the video should be public or private.

>This solves 2 of the questions asked above - 'can a delegated upload be set to private?' and 'Can I disable mp4 support?'.

```javascript
	if(req.body.public === "false"){
		public=false;
	}
	var mp4  = true;
	if(req.body.mp4Support === "false"){
		mp4=false;
	}
	var title = req.body.title;
	var descr = req.body.description;

	client = new apiVideo.Client({ apiKey: apiVideoKey});	
	
	
	let result = client.videos.create(title, {	"title": title, "mp4Support": mp4,
		"public": public, 
		"description": descr,					
	});

```

The response from the create video has a videoId that we will use as the container for the video we are about to upload.  This container is already built with the privacy settings requested on the webpage!

### One use upload token

Next, we'll create a delegated token with a TTL of 90 seconds.  Note - the TTL support is not yet in the Node SDK (it launched last week!), so we make HTTP requests to the API endpoint.

1. [Authenticate our apiKey](https://api.video/blog/tutorials/authentication-tutorial). This will return an authentication key in a second request for the token.  2. [Create a delegated token](https://docs.api.video/reference/api/Upload-Tokens) with the desired TTL (set to 90s in the code).  The response will give us the delegated token, and when it expires ("expiresAt").

```
var authOptions = {
			method: 'POST',
			url: 'https://ws.api.video/auth/api-key',
			headers: {
				accept: 'application/json'
				
			},
			json: {"apiKey":apiVideoKey}

		}
		console.log(authOptions);	
		request(authOptions, function (error, response, body) {
			if (error) throw new Error(error);
			//this will give me the api key
			
			var authToken = body.access_token;
			console.log(authToken);
			//now use this to generate a delegated toke with a ttl of 90s
			var tokenTTL = 90;
			var tokenOptions = {
				method: 'POST',
				url: 'https://ws.api.video/upload-tokens',
				headers: {
					accept: 'application/json',
					authorization: 'Bearer ' +authToken
				},
				json: {"ttl":tokenTTL}
	
			}
			request(tokenOptions, function (error, response, body) {
				if (error) throw new Error(error);
				var delegatedToken = body.token;
				var tokenExpiry = body.expiresAt;
				console.log("new token", delegatedToken);
				console.log("new token expires", tokenExpiry);
				var tokenVideoIdJson = {"token": delegatedToken,
										"expires":tokenExpiry,
										"videoId": videoId};
				res.setHeader('Content-Type', 'application/json');
				res.end(JSON.stringify(tokenVideoIdJson));

			});
```

Once these two requests have been made, we then send back a JSON response to the browser with the ```videoId```, and the delegated token information.

### Token Expiration

The token expires in 90 seconds - how can we ensure that the video will upload completely in 90s? The answer is that we cannot.  However, we'll use a trick.  If we break the video to be uploaded into small segments, we just need to ensure that the first *segment* of the video is uploaded in 90s. The chunkSize is set to 6 MB - so the first 6 MB must be uploaded in 90s.  

> We're balancing your customers' upload speed with the expiry of the upload token.  If 6 MB in 90s is causing failures - you can lengthen the token expiry - the minimum upload size is 5 MB.  
> If you think this is too generous - lower the tokenTTL. 


### Video Upload

>NOTE: Since this post was written, we've published a library to simplify JavaScript upload of videos [read the blog post to learn more](https://api.video/blog/tutorials/new-video-uploader-javascript-library).


Now we can come back to the JavaScript on the page, and the ```qReq.onload``` that I omitted above:



First we grab the parameters sent from the Node server. For the purposes of the demo, we display the delegated tokenId and the time the token expires (in GMT) on the page.

We then create the delegated video upload url by appending the token to the base url. We determine the number of chunks to upload, and the initial byterange (0-chunkSize) and send the videoId and the videoFile to the createChunk function.

The createChunk function slices up the video from 0 to chunkEnd-1 (the file Slice API lists the first byte IN the slice, and the first byte NOT in the slice). *It's easy to get an off by one error here!*

```
			function createChunk(videoId, start, end){
				chunkCounter++;
				console.log("created chunk: ", chunkCounter);
				chunkEnd = Math.min(start + chunkSize , file.size );
				const chunk = file.slice(start, chunkEnd);
				console.log("i created a chunk of video" + start + "-" + chunkEnd + "minus 1	");
				const chunkForm = new FormData();
				console.log("createChunk videoId",videoId +start+end);
				if(videoId.length >0){
					//we have a videoId
					chunkForm.append('videoId', videoId);
					console.log("added videoId");	
					
				}
				chunkForm.append('file', chunk, filename);
				console.log("added file");

				
				//created the chunk, now upload iit
				uploadChunk(chunkForm, start, chunkEnd);
			}
```

Then the api calls the uploadChunk function that sets the byterange header (off by one warning!) and uploads the video.  It also updates the upload progress.  When the segment is completed, the counter is incremented, and calls the createChunk function again:

```
function uploadChunk(chunkForm, start, chunkEnd){
				var oReq = new XMLHttpRequest();
				oReq.upload.addEventListener("progress", updateProgress);	
				oReq.open("POST", url, true);
				var blobEnd = chunkEnd-1;
				var contentRange = "bytes "+ start+"-"+ blobEnd+"/"+file.size;
				oReq.setRequestHeader("Content-Range",contentRange);
				console.log("Content-Range", contentRange);
				function updateProgress (oEvent) {
					if (oEvent.lengthComputable) {  
					var percentComplete = Math.round(oEvent.loaded / oEvent.total * 100);
					
					var totalPercentComplete = Math.round((chunkCounter -1)/numberofChunks*100 +percentComplete/numberofChunks);
					document.getElementById("chunk-information").innerHTML = "Chunk # " + chunkCounter + " is " + percentComplete + "% uploaded. Total uploaded: " + totalPercentComplete +"%";
				//	console.log (percentComplete);
					// ...
				} else {
					console.log ("not computable");
					// Unable to compute progress information since the total size is unknown
				}
				}
				oReq.onload = function (oEvent) {
							// Uploaded.
								console.log("uploaded chunk" );
								console.log("oReq.response", oReq.response);
								var resp = JSON.parse(oReq.response)
								videoId = resp.videoId;
								//playerUrl = resp.assets.player;
								console.log("videoId",videoId);
								
								//now we have the video ID - loop through and add the remaining chunks
								//we start one chunk in, as we have uploaded the first one.
								//next chunk starts at + chunkSize from start
								start += chunkSize;	
								//if start is smaller than file size - we have more to still upload
								if(start<file.size){
									//create the new chunk
									createChunk(videoId, start);
								}
								else{
									//the video is fully uploaded. there will now be a url in the response
									playerUrl = resp.assets.player;
									console.log("all uploaded! Watch here: ",playerUrl ) ;
									document.getElementById("video-information").innerHTML = "all uploaded! Watch the video <a href=\'" + playerUrl +"\' target=\'_blank\'>here</a>" ;

								}
								
				};
				oReq.send(chunkForm);
		
				
				
			}
```


These two functions dance back and forth - creating slices and uploading them - until the entire video is uploaded.  When the video is fully uploaded, api.video begins assembling the video, and encoding the file.  The response conatains the player URL for the video - which we put on the page for the viewer to see. If the video is set to private - it will be a private URL with a token - only good for one view.

## Private and secure video upload

I think we've done it!  A single use public token for video upload, and the ability to protect the video **before** it is uploaded.

Now you can be sure that your users will properly "stay on the path" with their video uploads.

large_img20200822121759.jpg

medium_img20200822121759.jpg

small_img20200822121759.jpg

thumbnail_img20200822121759.jpg

img20200822121759.jpg

 The code is availabe on [Github](https://github.com/dougsillars/privatedelegatedtoken) if you'd like to take a deeper dive, or create your own version.  And don't forget to try the demo [privatelyupload.a.video](https://privatelyupload.a.video/).

Was this tutorial/demo app useful to you?  Do you have other examples of how to use api.video that you'd live to see? Let us know in our [community](https://community.api.video) forum. 

Private video upload with a public token

medium_footpath.jpg

small_footpath.jpg

thumbnail_footpath.jpg

footpath.jpg

Private Live

JavaScript

api.video offers a number of simple APIs to create and share video.  To protect videos from being shared, we offer the concept of private videos - where the ```public``` token for the video is set to ```false```.

These [private videos](https://api.video/blog/tutorials/tutorial-private-videos) have a URL token that can be used just once, and cannot be shared. To authenticate the token, we insert a custom header that must also be validated with the URL token.

If you use the api.video player - there is no development required - we do all the lifting of adding the authentication header for you.

If you are using a different player, you need to recieve this header from cdn.api.video and insert this header on each subsequent request.  To learn how, read on!

## Retrieving the header

For each unique view of a private video, you must generate a unique URL token.  It will look something like this:

>https://embed.api.video/vod/vitkytkieTnEvUjKE0VQpd2?token=c7cc5f68-1c98-49a0-a1c3-406e95d95228

Using Chrome DevTools, we can see what happens when we request this url:





large_picture-of-requests-in-chrome-devtools.png

medium_picture-of-requests-in-chrome-devtools.png

small_picture-of-requests-in-chrome-devtools.png

thumbnail_picture-of-requests-in-chrome-devtools.png

picture-of-requests-in-chrome-devtools.png

The 4th request is to cdn.api.video for the player.json.  The first request to this domain for a private video (either for the .mp4, the player.json, or the manifest.m3u8) will have a custom header in the response (```X-Token-Session```).


medium_x-token-session-in-headers.png

small_x-token-session-in-headers.png

thumbnail_x-token-session-in-headers.png

x-token-session-in-headers.png


This header and value must be sent on every subsequent request to cdn.api.video to ensure playback.

If you use the api.video player, each subsequent request has this header added  automatically.  For example, here is the request for the video thumbnail.jpg (in Safari, with a different session token):

request for the video thumbnail.jpg (in Safari)

large_request-for-the-video-thumbnail-jpg-in-safari.png

medium_request-for-the-video-thumbnail-jpg-in-safari.png

small_request-for-the-video-thumbnail-jpg-in-safari.png

thumbnail_request-for-the-video-thumbnail-jpg-in-safari.png

request-for-the-video-thumbnail-jpg-in-safari.png

At the bottom of the header list is the ```X-Token-Session```. 

## Using a different player

With a different video player, the code to insert this custom header must be added.  So lets walk through the steps to add a new request header in your code.

### Getting the session header

To retrieve the session header, simply request the first file from api.video (typically this is the m3u8 manifest file). It will look something like:

```
https://cdn.api.video/vod/vitkytkieTnEvUjKE0VQpd2/token/8e19097c-8310-4ce3-acba-206378119bc5/hls/manifest.m3u8
```

If you request this file from your player (or you can test just by loading this url in Safari), you'll receive the response with a lot of headers:

```
Timing-Allow-Origin: *
Cache-Control: no-store, no-store
Accept-Ranges: bytes
Access-Control-Allow-Origin: *
Content-Length: 590
Via: 1.1 PSfgblPAR2xf192:2 (W), 1.1 PSygldLON4zd14:8 (W), 1.1 PSygldLON2ew56:2 (W)
X-XSS-Protection: 1; mode=block, 1; mode=block
Date: Fri, 23 Oct 2020 10:02:57 GMT
Access-Control-Expose-Headers: Content-Type, Content-Length, Content-Range, X-Token-Session, Vary, Origin
X-Frame-Options: SAMEORIGIN, SAMEORIGIN
Access-Control-Allow-Credentials: true
Content-Type: application/vnd.apple.mpegurl
ETag: "5e8f75e8-24e"
X-Content-Type-Options: nosniff, nosniff
Last-Modified: Thu, 09 Apr 2020 19:22:16 GMT
x-proxy-cache: HIT
Server: PWS/8.3.1.0.8
x-ws-request-id: 5f92aa50_PSygldLON2ew56_14724-24181
x-token-session: 284a505f-d556-4de5-9498-c68260927551
x-px: ms PSygldLON2ew56LHR,ms PSygldLON4zd14LHR,ms PSfgblPAR2xf192CDG(origin)
```

Now we have the x-token-session for the playback of the video, and we must include this in each subsequent request.

### Minimal working example

The following piece of code shows how to retrieve the source file of a private video from a token value (error handling has been omitted for readability reasons).


## Adding the token to your header


Depending on the type of resource to retrieve, adding the X-Token-Session header may not be as straightforward as in the example above.

Below are some tips that you might find useful.

### Using MediaSource capabilities

If you manage the video tag yourself, you can use the [MediaSource interface](https://developer.mozilla.org/fr/docs/Web/API/MediaSource) to add headers to video files related requests.

### Using URL.createObjectURL() method

[URL.createObjectURL](https://developer.mozilla.org/fr/docs/Web/API/URL/createObjectURL) might be useful for some kinds of assets. For instance, you could display a video poster using an img tag with the following code:


### Using a service worker

[Service workers](https://developer.mozilla.org/fr/docs/Web/API/Service_Worker_API) can be used to intercept and modify any request made by your application and thus it gives you the ability to add headers. 


### Using video.js based players

If your player is based on [video.js player framework](https://videojs.com/), you can redefine the beforeRequest method on the xhr object of videojs.Hls . This will give you the ability to add the header on any video request. 


If you have any questions about this tutorial or would like to learn more about api.video please join our [community forum](https://community.api.video/). 

Inserting custom headers

large_inserting-custom-headers.jpg

medium_inserting-custom-headers.jpg

small_inserting-custom-headers.jpg

thumbnail_inserting-custom-headers.jpg

inserting-custom-headers.jpg

When it comes to publishing videos online, there are many ways that your content might be shared.  There are videos that you want to share with the whole world. For other videos you might want to restrict the audience to just a handful of people, or maybe even just one person. api.video's private video solution can help you restrict who can watch the videos you have on the web.

By default, when you [upload a video](https://api.video/blog/tutorials/video-upload-tutorial) with api.video, the video is public, meaning that anyone with the link to the video can watch it, like the video below:

<iframe src="https://embed.api.video/vod/vi4blUQJFrYWbaG44NChkH27"  height="540px" frameborder="0" scrolling="no" allowfullscreen=""></iframe>

However, for videos that need to be restricted, you can use private videos to deliver the content securely to specific users. Let's learn how. If you're interested in seeing the API reference documentation for this project, go here:
[Delegated upload](https://docs.api.video/reference/api/Upload-Tokens).

## Private videos

How can we keep our videos private?  When creating a video with api.video, you can set the “public” attribute to false.  The video is published exactly the same way, but a unique token is added to the url:

https://embed.api.video/vod/vitkytkieTnEvUjKE0VQpd2?*token=4a9a10fd-6c03-457f-a6c5-6d73f2c9fa85*

This token is valid exactly once - so the video cannot be shared with others. When this url is accessed, the first response from *cdn.api.video*  will contain a new header ```X-Token-Session```, that will be used to validate every subsequent request at cdn.api.video.  As long as the session header/tokens match, the viewer is authorised to watch the video and the video will play.  If there is not a match, video playback will fail.

### Generating the URL token

To generate the url token, you must [authenticate yourself](https://api.video/blog/tutorials/authentication-tutorial) with api.video. Next, make a request for the video:

The response JSON will contain urls for your video with unique tokens.  

Here is a snip of the JSON response:

Every time you request the video, you will generate a new token that can be used exactly once.

## Private videos in practice

Once you generate a unique url with a private token, your application can request the video for playback. The next step will vary slightly depending on the video player used:

### (Recommended) Using the api.video player 

If you use the api.video player (using the ```iframe``` or ```player``` assets in the JSON response), the ```X-Token-Session``` header/session control is done automatically for you, and there is no further development required.  This is our recommended implementation.

### Using a different video player

If you are using a different video player to display your video, you will need to capture the ```X-Token-Session``` value from the initial *cdn.api.video* response, and submit this header/value combination in every subsequent request to cdn.api.video. To learn more about inserting custom headers, [read this tutorial](https://api.video/blog/tutorials/inserting-custom-headers).


medium_private-videos-sequence-diagram.png

small_private-videos-sequence-diagram.png

thumbnail_private-videos-sequence-diagram.png

private-videos-sequence-diagram.png



Once you capture this header, you have 2 options with subsequent requests for the private video:

1. Add the the header on subsequent requests to authenticate the private video.
2. Append the value of the header in the URL parameter avh for all additional requests ```?avh=<token value>```.

## Conclusion

Private videos allow you to control who is able to view the video through the use of unique tokens.  If the user has a valid token and X-Token-Session header in the request or url parameter, the user is able to see the video.  If any of the authetication steps fail, playback is not authorised, and no video will play to the end user.

If you have any questions or suggestions, please share them on our [community forum](https://community.api.video/). If you are ready to start building with api.video now, create your account [here](https://dashboard.api.video/register). Thank you for reading! 

Creating private videos

large_privatevideo.png

medium_privatevideo.png

small_privatevideo.png

thumbnail_privatevideo.png

privatevideo.png

codec

small_cedric.jpeg

thumbnail_cedric.jpeg

cedric.jpeg

Cédric Montet

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

large_Blog_Zero Cost (2).png

medium_Blog_Zero Cost (2).png

small_Blog_Zero Cost (2).png

thumbnail_Blog_Zero Cost (2).png

Blog_Zero Cost (2).png

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

Erikka Innes

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)!_

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

Private Videos