Thumbnail Query API (Deprecated)

For every video uploaded into your Backlot account, the Ooyala Transcoding system produces a thumbnail image roughly every 15-30 seconds.

Note: This software is deprecated. Use the latest version.

The encoding widths in your processing profile dictate the sizes of the images produced. Specifically, for every encoding width X in your processing profile, thumbnail images are produced at size X and size X/3. Any query to the Thumbnail API for a particular size of an image will as a result search against these sizes. If an exact match is not possible, the next closest sized thumbnail image will be returned. It is important to note that the thumbnail images produced maintain the aspect ratio of the original file uploaded into Backlot.

Note: Custom promo images uploaded through Backlot or the API will be returned by a thumbnail query and will not be processed and have multiple sizes made available. The thumbnail image is different from the promo image; the original promo image can be accessed through the Query API interface.

As in the Query API example, Thumbnail queries are generated using a signed REST-style GET request to

Required Parameters:

  • pcode – Account Identifier
  • expires – Query expiration date in seconds since epoch (00:00:00 1/1/1970 GMT)
  • embedCode – Content Identifier
  • range – Specifies thumbnail indices to be returned. Format: <from index>-<to-index>. For example, to get first 5 thumbnails (from index 0 to index 4) use this value: range=0-4. If the requested range is larger than the number of thumbnails generated, we will return all that are available.
  • resolution – Provide the size of the image you will use to display the thumbnail. The parameter format is <width>x<height>, e.g. resolution=320x240. Please note that we may return a larger JPEG than requested, but with a higher compression rate. You may resize this result to the desired size.
  • signature – The digital signature of the request. The signature should be calculated using SHA-256 with the signature generation rules.

Example of a request<pcode>&embedCode=<embedCode>

Thumbnail Query Result

The result of a query is an XML document served as a response body. The root tag is <thumbnails> with all matching thumbnails included as <thumbnail> tags in that list.

The root <thumbnails> tag has 2 attributes:

  • embedCode – Requested content ID
  • aspectRatio – The aspect ratio of the image as a non-reducible fraction. For example 4/3 or 16/9. Please note that this attribute contains the aspect ratio of the image and always reflects the aspect ratio of the actual movie.

Each <thumbnail> tag contains:

  • index attribute – Zero-based index of thumbnail.
  • timestamp attribute – Time of the video, in milliseconds, at which the thumbnail was created.
  • URL of thumbnail as tag body.

Example of Thumbnail Query Result

<?xml version="1.0" encoding="UTF-8"?>
<thumbnails aspectRatio="4/3" estimatedWidth="240" embedCode="kxYm06gFKXEleIHdyXNKeefx-QAu2yVp" requestedWidth="340">
  <thumbnail timestamp="0" index="0"></thumbnail>
  <thumbnail timestamp="9933" index="1"></thumbnail>