Caption Order API

IVA’s Caption Order API allows you to submit orders to have our catalog of videos transcribed into captions (fees apply). For information on retrieving your captions for use in your own custom player, click here.

Overview

To make a proper request for a caption, you will need:

  • IVA Customer Number
  • Security Token
  • Language ID for the caption
  • IVA Published ID of the Video with Caption

The IVA customer number and security token are provided by your sales representative or by our client services team. When you request a caption to be made, make sure to store the caption ID, published ID and Language ID.  Otherwise you can query our OData 2.0 API and look at the captions entity.  Be sure to use the developerID associated to your customer account or you will not see the captions. Once you have created a proper URL, pass it to your player and the link will do an instant 302 redirect to the caption file on our CDN.

Step 1

Start with a base URL:

http://video.internetvideoarchive.net/captionorder.ashx

SSL

All of IVA’s captions are available via HTTPS.

Example:

https://video.internetvideoarchive.net/captionorder.ashx

Step 2

Pick your options. The chart below lists all the required parameters that you must pass to the API to get back the proper caption.

Caption Order API Parameters

ParameterDescription
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
publishedid (required)Every video asset in our library is given a unique number known as its Published ID.
languageid (required)Language of the caption to return. Current supported languages:

Arabic - (languageid = 26)
English - (languageid = 0)
French - (languageid = 3)
German - (languageid = 10)
Hebrew - (languageid = 15)
Hindi - (languageid = 36)
Italian - (languageid = 11)
Japanese - (languageid = 7)
Korean - (languageid = 13)
Mandarin Chinese - (languageid = 16)
Portuguese - (languageid = 17)
Russian - (languageid = 4)
Spanish - (languageid = 2)
Traditional Chinese - (languageid = 8)
Turkish - (languageid = 64)
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.

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.

Step 4

When the request succeeds, the API will respond with a HTTP 200 Status code indicating acceptance of the order and will return a JSON response with a Caption ID that you should keep alongside the Published ID of the IVA video asset you had captioned.

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/captionorder.ashx?customerid=12345&publishedid=126095&languageid=0&fmt=2&e=1171159092&h=1dc7a1455f4a7f5f7f74fd32093a201f

Customers can check their hash against our Hash 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/captionorder.ashx?customerId=123456&publishedid=126095&languageid=0&e=1171159092

Psuedo-code to Generate Hash:

MD5(lcase(1234http://video.internetvideoarchive.net/captionorder.aspx?customerId=123456&publishedid=126095&languageid=0&e=1171159092))

Hash = c13c876ea56c6124cba712c050a7ae69

Finished URL:

http://video.internetvideoarchive.net/captionorder.aspx?customerId=123456&publishedid=126095&languageid=0&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)