Video API

IVA’s Video API allows you to programmatically generate links that will return any of IVA’s over 100,000 video assets. The Video API allows you to take an IVA Published ID and create a link to the video asset. These links will return a video and require a paid subscription.

Note: If you are using IVA’s player you do not need to use our Video API. The player handles video delivery by itself.

Overview

Paid subscribers to IVA’s service use our Video API with our Published ID’s to deliver videos to the player of their choice. To make a proper request for a video, you will need a customer ID number, a security token, and a published ID. The customer ID number and security token are provided in your welcome letter. Published ID’s are available two ways: If you have your own data, use our OData API to create a query and do your own matching. If you are using a data provider use one of the matching tables that we provide for our data partners. Once you have created a proper URL, pass it to your player and the link will do an instant 302 redirect to the file on our CDN.

Step 1

Pick your base application URL. There are a few application URLs from which to choose. The chart below will show indicates which bases go with which formats. Pick the one that corresponds to the video format you prefer or use the generic player.aspx.

ISM:

http://video.internetvideoarchive.net/video.ism/Manifest?cmd=6&publishedid=91&customerid=12345&fmt=12&e=13500092&h=298y9386666

MP4:

http://video.internetvideoarchive.net/video.mp4?cmd=6&publishedid=91&customerid=12345&fmt=4&e=13500092&h=298y9386666

XML:

http://video.internetvideoarchive.net/video.xml?cmd=3&publishedid=91&customerid=12345&fmt=4&e=13500092&h=298y9386666

DASH:

http://video.internetvideoarchive.net/video.mpd?cmd=6&publishedid=91&customerid=12345&fmt=14&e=13500092&h=298y9386666

HDS:

http://video.internetvideoarchive.net/video.f4m?cmd=6&publishedid=91&customerid=12345&fmt=13&e=13500092&h=298y9386666

M3U8:

http://video.internetvideoarchive.net/video.m3u8?cmd=6&publishedid=91&customerid=12345&fmt=11&e=13500092&h=298y9386666

SSL

All of IVA’s video content is available via HTTPS.
Example:

https://video.internetvideoarchive.net/player.aspx?customerId=12345&cmd=6&videokbrate=750&fmt=4&publishedid=1757&e=1171159092&h=1dc7a1455f4a7f5f7f74fd32093a201f

Step 2

Pick your options. The chart below lists all the required and optional parameters that you can/must pass to the API to get back the proper video.

Video API Parameters

ParameterDescription
cmd (required)Default is cmd=6. This will validate the link and do a 302 redirect to the content. Be sure to use the appropriate base application URL for the format you want. Note: Adaptive technologies require cmd=6. Alternate cmd=3.
fmt (required)This option tell what format you would like returned. Current options are:

MP4 – (fmt=4) Good for all devices and situations.
HLS – (fmt=11) Good for devices and situations that have access to good bandwidth speeds.
HSS – (fmt=12) Good for devices and situations that have access to good bandwidth speeds.
HDS – (fmt=13) Good for devices and situations that have access to good bandwidth speeds.
Dash – (fmt=14) Good for devices and situations that have access to good bandwidth speeds.

Note: If a device does not support HLS or Flash the IVA player will default back to HTML5 and use the MP4 format.
customerid (required)ID’s are assigned to paid subscription users by their salesman. It is a unique ID used for security and customization purposes. Ex customerid=45678
videokbrate (required)This specifies the speed of the file you want to play. Consult the Encodes Entity to see what speeds and formats are available for each video asset. Available formats and speeds are:

MP4 – 80, 212, 450, 750, 1500, 2500(HD sources only) Kbps
HLS, HSS, HDS, Dash are multi-bitrate formats and do not require VideoKbrate. You can however, use minrate and maxrate parameters to adjust bitrates.
publishedid (required)Every video asset in our library is given a unique number known as its Published ID. Ex: publishedid=123345
e (required)Time when the URL expires. This value is calculated in the number of seconds since 01/01/1970. Click here for a time converter.
h (required)The hash code for the requested URL. You will create this unique number for every video request by using your Secret Token and doing an MD5 hash of the entire link including the ‘e’ parameter. Check out the Encryption Documentation below.
startThe start option can be used to tell supported players where to start the video. This is useful when detecting buffering events and you want to start the video at the point of the event. For example: Generate links to a few different videokbrates. If a buffering event occurs you can tell the player to switch to a lower videokbrate and append the time in seconds to start. To take advantage of this, make sure your player supports range requests. You do not need to MD5 hash the start or end options when creating a URL as long as you append it after the hash code in the link. Format: start=25 where 25 is the number of seconds into the video you would like to start.
endThe end option works like just like the start option only that it tells the player when to stop playing the video. Format end=55 where 55 is the number of seconds into the video from the beginning when to stop the video.
minrateUsed with Adaptive bitrate technologies like HLS, HSS, HDS, and Dash. This parameter is in bits per second (bps). To set a minimum bitrate of 1200 Kbps, use minrate=1200000.Currently IVA offer 600Kbps, 1200Kbps, 2000Kbps, 2500Kbps(HD 720p)* and 5000Kbps(HD 1080p)*
*-when source is available. Use the following values to limit (212000, 350000, 600000, 1200000, 2000000, 2500000, 3500000)
maxrateUsed with Adaptive bitrate technologies like HLS, HSS, HDS, and Dash. This parameter is in bits per second (bps). To set a maximum bitrate of 1200 Kbps, use maxrate=1200000.Currently IVA offer 600Kbps, 1200Kbps, 2000Kbps, 2500Kbps(HD 720p)* and 5000Kbps(HD 1080p)*
*-when source is available. Use the following values to limit (212000, 350000, 600000, 1200000, 2000000, 2500000, 3500000)
subPass a unique string with this variable to segment reporting inside of Media Manager. For example if you wanted to see the video traffic specific to your iOS application you could have all the links generated with sub=iOS. When you look at the analytics you can choose to see the information for any of the links that used that sub tag. Be sure to add this before the hash code.

Using Start and End parameters

Start and End parameters do exactly what they say. They tell the video when to start and when to end.  This is only supported in HTML5 players.

Example: start and end

http://video.internetvideoarchive.net/player.aspx?cmd=6&fmt=4&customerid=12345&videokbrate=2500&publishedid=244133&e=312456677&h=74lkkjsfalksdjf&start=34&end=54

Using minrate and maxrate parameters.

Example: HLS Link using the minrate and maxrate:

http://video.internetvideoarchive.net/player.aspx?cmd=6&fmt=4&customerid=12345&minrate=1200000&maxrate=2500000&publishedid=244133&e=312456677&h=74lkkjsfalksdjf

Step 3

Apply security settings. IVA requires customers to secure the links they are making by setting a time to live (TTL) and applying an MD5 hash code to the link to prevent deep linking from unwanted sources. To make the hash you will need your customer account number and your security token. Read the steps below for more information on creating this hash code.

Hash Code

The hash code (h in the URL) is an MD5 hash appended to the end of the request to the player. Encrypting your security token and URL to the video creates this hash code.

Example:

http://video.internetvideoarchive.net/player.aspx?customerId=12345&cmd=6&videokbrate=750&fmt=4&publishedid=1757&e=1171159092&h=1dc7a1455f4a7f5f7f74fd32093a201f

Customers can check their hash against ourHash Code Generator.

The logic (in Visual Basic Script) to create a hash is as follows:

Dim Md5Hash As String ' The hash code to append to the URL
Dim URL As String ' The URL containing publishedId, customerId, e, etc...
Dim RequestUrl As String ' The URL and the hash (a valid URL)
Dim SharedSecurityToken As String ' The constant shared token between IVA and you.

Md5Hash = MD5(lcase(Sharedsecuritytoken & URL)) ' calls a MD5 function to create a hashcode

RequestUrl = URL & "&h=" & Hash & "&Stuff not included in the hash if you want."

Note: Make sure that you put your security token before the URL. See the example below.

Example with Security Token = 1234

URL:

http://video.internetvideoarchive.net/player.aspx?customerId=12345&cmd=6&fmt=4&videokbrate=750&publishedid=1757&e=1171159092

Psuedo-code to Generate Hash:

MD5(lcase(1234http://video.internetvideoarchive.net/player.aspx?customerId=18088&cmd=6&fmt=4&videokbrate=750&publishedid=1757&e=1171159092))

Hash = c13c876ea56c6124cba712c050a7ae69

Finished URL:

http://video.internetvideoarchive.net/player.aspx?customerId=12345&cmd=6&fmt=4videokbrate=750&publishedid=1757&e=1171159092&h=c13c876ea

Below are a number of ways to create an MD5 hash using common programming languages:

Important: Although MD5 is available in ActionScript 2.0 we recommend not including your security token inside an SWF as SWFs can easily be decompiled allowing other sites to use your IVA account.

Expiration

In order to prevent a valid URL from being “hot linked” for an extended period of time an expiration, or Time To Live (TTL) is required. The expiration for the video.internetvideoarchive.net/player.aspx is measured in the number of seconds from 1/1/1970. Below is a vbscript example of creating a TTL of 3 minutes. (Server date is based on Greenwich Mean Time, or GMT.)

Public Function makettl()TimeoutDate = DateAdd("n", 3, Now)

makettl = DateDiff("s", "01/01/1970 00:00:00", TimeoutDate) ' convert to Unix time

End Function
GMT Offset - the difference between your server's time and GMT Time.One way to get GMT Offset is to use jScript: GMT Offset = 0 - new Date().gettimezonetoffset()

// GMT offset in minutes of the server (sign inversed to bring into line with reality)