Getting previews

Last updated
Save as PDF
Share
1. Share
2. Tweet
3. Share

How to request preview images in different sizes from FotoWeb.

Overview

Each asset has one or more preview images of different dimensions. Each preview image of each asset has a unique URL, which is used to request the actual image. The URLs, as well as other information about each preview image, is contained within the other information about an asset and can be found in the asset representations of a single asset as well as in the asset list representation of a collection.

To get preview information and preview image URLs, a client therefore needs to request an asset or asset list representation first.

Preview images of smaller size are typically used as thumbnails and do not have watermarks. Preview images of larger size are typically used as previews and may carry watermarks depending on the configuration of the archive to which the asset belongs. The API may also provide small thumbnails of square size, which may come in handy in some user interfaces that require images to be shown as squares. All other preview images are delivered in the same aspect ratio as the original asset (if applicable).

For video assets, preview images are created from representative poster frames of the video. For document assets, preview images are created from the first page of the document. For other, non-image assets, preview images are icons representing the type of the asset.

JSON format

Preview information is embedded into asset information in asset and asset list data representations. The general format is an array of objects describing each available preview image:

previews: [
  {
    size: 800,
    width: 800,
    height: 535,
    href: "/fotoweb/cache/5001/testarchive/Oslo/2014/03/DSC_0058_2.t553f5358.m800.x4a9a0182.jpg",
    square: false
  },
  { ... },
  ...
]

Preview attribute legend

Attribute	Explanation
Size	Size of the preview image (maximum of width and height). Can be used for selecting the appropriate preview image based on factors such as screen resolution or the size of the context where the preview image should be rendered.
width	Display width of the preview image in pixels.
height	Display height of the preview image in pixels.
href	URL for requesting the preview image. See remarks below.
square	Specifies whether the preview image retains its original proportions (false) or is cropped to a square (true). See remarks below.

Remarks

Preview and quick rendition URLs are ephemeral, i.e., they have a limited lifetime and are designed to be used immediately. They are NOT designed for long-term storage or embedding. Immediately here means within a few seconds or minutes, whereas “long-term” means within hours or days or permanent.

This means that the following usages of rendition URLs are safe:

Immediately showing the rendition image in the UI of a native application
Immediately downloading the rendition image for storage or further processing in a third-party component
Embedding the rendition URL in an ephemeral / dynamically generated web view.

whereas the following usages of rendition URLs are NOT safe:

Storing the rendition URL in a third-party component for a longer time
Embedding the rendition URL in a web view that is expected to remain valid long-term, such as a blog post or static website.

To obtain embeddable rendition URLs that remain valid long-term, please consider using CMS export or the Export API.

Accessing rendition URLs does not require authentication or access tokens, so they can be embedded into (short-lived) web views without the need to expose access tokens to user agents. Rendition URLs are protected by signatures to prevent unauthorized access. A valid rendition URL can only be obtained via the FotoWeb API or UI by authorized clients or users.

It is not possible for integrations to construct valid rendition URLs themselves. The format, signature algorithm, expiry time, and expiry conditions for rendition URLs are implementation-defined and subject to change, and any information provided about these by Fotoware is for review or debugging purposes only. Under no circumstances should integrations rely upon them. If you need a way to produce valid rendition URLs in an integration, submit a feature request to Fotoware. Also, note that the Preview Agent API is deprecated and should not be used in new integrations.

Square thumbnails are cropped versions of the original image (except for non-image assets, whose preview images are icons). If the original image is in landscape format, then the cropped area is in the center of the original image and covers its whole height. If the original image is in portrait format, the cropped area is at the top of the original image and covers its whole width.

Clients should not assume that preview images of specific sizes are available. The available sizes are determined by the server and are the same for all assets. Clients should select the available size which is most suitable. It is not possible for a client to request arbitrary preview sizes, as that would result in bad (pre-)caching of preview images. However, if a specific size is required by an API client, it is possible to use quick renditions.

Example: Getting a preview image of a specific size

In all examples, it is assumed that asset is the JSON representation of an asset, taken either from a single asset or from an element of an asset list.

The following example gets the preview image whose size is closest to and not larger than 200 pixels. Note that it only accepts previews in the original aspect ratio, so it must check that the preview image is not square.

preview_size = 800   # The ideal size of the preview image
best_preview = None  # JSON representation of preview image with best size
for preview in asset.previews:
  if preview.size <= preview_size and not preview.square:
    if best_preview is None or best_preview > preview.size:
      best_preview = preview

if best_preview is not None:
  preview_url = best_preview.href
else:
  # ERROR: No suitable preview found

Code example: Getting thumbnails from a collection

This example shows how to get thumbnails of a specific size for all assets in part of an asset list. The JSON representation of the asset list is given as assets. The resulting list of thumbnail URLs is stored in the thumbnails array. The code from the previous example is used to select thumbnails of the correct size for each asset.

thumbnail_size = 200   # The ideal size of the thumbnail images
thumbnails = []        # The array of thumbnail URLs
for asset in assets:
  best_preview = None
  for preview in asset.previews:
    if preview.size <= thumbnail_size and not preview.square:
      if best_preview is None or best_preview > preview.size:
        best_preview = preview
  if best_preview is not None:
    thumbnails.append(best_preview.href)
  else:
    # ERROR: No suitable thumbnail image found for this asset