Skip to main content
Documentation & User Guides | FotoWare

Getting previews

How to request preview images in different sizes from FotoWeb.


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.


Preview images are public and cacheable, so requesting a preview image does not require authentication of any kind. However, each URL is protected by a signature to prevent unauthorized clients from computing URLs of preview images that have not been provided by the server through authorized requests. For example, a client that has received the URL of a preview image of a specific size with a watermark cannot compute the URL of a preview image of a different asset or of a different size or without the watermark. To get other preview images, the client has to request asset information through the FotoWeb API, which requires authorization. This ensures that previews can be delivered fast without compromising security.

It is discouraged to store preview image URLs should in third-party databases or other types of long-term storage. URLs of preview images may change between versions of FotoWeb or when making configuration changes. An integration which exports these URLs to third-party systems for long-term storage must be able to regenerate all exported URLs from the original asset. This can be done by storing the URL ("href") of the asset in addition to the preview image URL and requesting the new preview image URL through the FotoWeb API if necessary.

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, then 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 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 a square image.

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
  # 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:
    # ERROR: No suitable thumbnail image found for this asset
  • Was this article helpful?