Custom Stills Service

The Custom Stills Service allows you create HD quality screen grabs from the stills picked for a video asset. As you can see below we created 4 different custom sizes the same still. Every video asset we add gets a still picked for it by our Production Staff. By default we do provide access to a 320×240 still for the video asset through the IVA OData API but with this new service you have the options of selecting the aspect ratio (16×9 or 4×3) and the size of the image. You create links to these stills very much like you do with making links to the trailers with our Video API. For this you will need your customer number and your secret token.

Custom Stills Example

Requests

All requests for images will follow these guide lines.

Application URL: http://images.internetvideoarchive.net/resizer or http://images.internetvideoarchive.net/resizer.jpg

When finished your URL should look like this:

http://images.internetvideoarchive.net/resizer?width=35&height=35&customerid=12345&aspectratio=4x3&publishedid=78568&e=1315876167&h=58128c241e9709163b814574d9761812

Custom Stills Service Parameters

ParameterDescription
Publishedid (required) Unique identifier Internet Video Archive uses to reference both entertainment programs and Video Assets.
Width (optional)Desired Width of Image. Maximum width in our catalog is 1280. To get the source photo, do not pass this parameter (see: Height)
Height (optional)Desired height of Image. Maximum height in our catalog is 720. To get the source photo, do not pass this parameter (see: Width)
AspectRatio (required)Desired Aspect Ratio from our catalog of Image’s. We have two ratio’s available, 16×9(Widescreen) or 4×3(Standard).Choose aspect closest to your desired dimensions to ensure image

quality is maintained.
CustomerId (required)Unique id assigned by Video Detective. This ID is used for security and customization purposes. Ex: customerid=45678
e (required)Time when the URL expires. This value is calculated in the number of seconds from 01/01/1970 00:00:00 based on GMT. Click here for a Unix Time converter.
h (required) Hash code for the requested URL. This is the MD5 hash code your server will need to generate for each request for video. The MD5 hash is based on your security key and the

entire URL left of the hash code itself. If the application detects any of the parameters have been modified, the request will be denied. This URL encryption ensures that requests come only from the source.
alturlURL to content that IVA will redirect to when an image is not yet available.  By default, IVA will return a 1×1 image. By providing an alternate URL, developers can point to their own Image Not Available image to provide a consistent user interface.

URL Encryption Documentation

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)

Notes

For each request, If we do not have an image to match your request, we will attempt to generate the image for you. We will in the meantime return a 1×1 transparent pixel image.

The generated image will be available within a few minutes. This is limited only to content we have for the requested publishedid.

*Image Quality is dependent on availability of images in catalog.*

SSL

Images through this services are also available through HTTPS.

Example:

https://images.internetvideoarchive.net/resizer?width=1280&height=720&customerid=12345&aspectratio=16x9&publishedid=75456&e=1315876167&h=58128c241e9709163b814574d9761812

Examples

Requesting 1280×720 photo for movie UP with aspect ratio of 16×9 widescreen:

http://images.internetvideoarchive.net/resizer?width=1280&height=720&customerid=12345&aspectratio=16x9&publishedid=75456&e=1315876167&h=58128c241e9709163b814574d9761812

Requesting 960×720 Image for movie The Dark Knight with aspect ratio of 4×3 standard:

http://images.internetvideoarchive.net/resizer?width=960&height=720&customerid=12345&aspectratio=4x3&publishedid=999961&e=1315876167&h=58128c241e9709163b814574d9761812

Requesting 400×320 photo for Tron Legacy asking for 4×3 standard:

http://images.internetvideoarchive.net/resizer?width=400&height=320&customerid=12345&aspectratio=16x9&publishedid=778984&e=1315876167&h=58128c241e9709163b814574d9761812

Requesting 16×9 source photo (width/height variable) for Tron Legacy:

http://images.internetvideoarchive.net/resizer?customerid=12345&aspectratio=16x9&publishedid=778984&e=1315876167&h=58128c241e9709163b814574d9761812

Requesting 4×3 source photo (width/height variable) for Tron Legacy:

http://images.internetvideoarchive.net/resizer?customerid=12345&aspectratio=4x3&publishedid=778984&e=1315876167&h=58128c241e9709163b814574d9761812

Using OData API 2.0 and Custom Stills Service to Get HD Performer Photos

Did you know that IVA tags performers in each hand picked sill we select? We do! The example below shows you how to get all the IVA Published ID’s for the videos where a performer is tagged based on their Performer ID.


OData 2.0 API URL for Jennifer Lawrence, Performer ID: 115935 
http://api.internetvideoarchive.com/2.0/DataService/PerformerMappingToHdPhotos()?$filter=PerformerId eq 115935 and HdTitlePhoto/AspectRatioId eq '16x9'&$expand=HdTitlePhoto&$select=HdTitlePhoto/publishedId&format=json&developerid={yourID}
 

The API call above will return a list of Published ID’s. Use those ID’s with the Custom Stills Service to get those photos.