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.
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.
Start with a base URL:
All of IVA’s captions are available via HTTPS.
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
|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.|
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.
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.
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.
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
Psuedo-code to Generate Hash:
Hash = c13c876ea56c6124cba712c050a7ae69
Below are a number of ways to create an MD5 hash using common programming languages:
- ASP: http://mediamanager.internetvideoarchive.com/md5.txt
- PHP: http://us3.php.net/md5
- ASP.NET: Use the built in function FormsAuthentication.HashPasswordForStoringInConfigFile(StringToEncrypt, “MD5″)
- ActionScript 2.0: There are various scripts available. We have successfully tested this one.
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.
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)