Thumbnail resources

A thumbnail resource defines a directory on the file system where the thumbnail database files will be stored.

Adding a thumbnail resource

Add a thumbnail resource using POST /resource.

POST /resource
Content-Type: application/xml

<?xml version="1.0"?>
<ResourceDocument xmlns="">

Reading thumbnails

The thumbnails in that directory will then be available from the API as described on Thumbnail resource handling. For example, all thumbnails can be listed using GET /thumbnail/(resource-id).

GET /thumbnail/VX-2
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="">

However, you would typically not access thumbnails from that resource directly. Instead, fetch thumbnails for an item using GET /item/(item-id)/thumbnailresource or using the thumbnail content parameter.

GET /item/VX-7/thumbnailresource
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="">
GET http://localhost:8080/API/thumbnail/VX-1/VX-7;version=0
<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<URIListDocument xmlns="">

How thumbnails are saved on disk

The thumbnails can be stored either in a database form or as one file per thumbnails (New in 4.2.2.).

Thumbnails are stored in the resolution and format as requested when the thumbnails were created, and it’s not possible to for example request a thumbnail as a PNG if it has previously been created as a JPEG.


The thumbnail path as specified in the ResourceDocument should have the format

  • path (e.g. /srv/media/thumbnails/), or
  • file URI (e.g. file:///src/media/thumbnails/)

Thumbnails are stored in a separate directory and database - one for each item. Vidispine will automatically migrate the databases during runtime if necessary, so no special action is required when updating Vidispine to a newer version or when restoring an old thumbnail backup on a newer system.

One file per thumbnail

New in version 4.2.2.

The thumbnail path as specified in the ResourceDocument should have the format

  • URI with the direct+ prefix (e.g. direct+file:///src/media/thumbnails/

All URIs supported as Storage method URIs are supported.

Using a tree structure for thumbnails

Putting all files in the same directory of a storage can cause degraded performance on some file systems.

By setting the configuration property thumbnailHierarchy, the naming convention for the thumbnails’ folders is changed to site-id - number1 / number2. The number set in thumbnailHierarchy controls the size of number2.

The thumbnailHierarchy works in the same way as fileHierarchy does for files. See Using a tree structure for files for an example. The property works both for the database thumbnail storage and the direct thumbnail storage.


Changing the thumbnailHierarchy property will cause old thumbnails to be lost. If you need to change the value on a system in production, please contact Vidispine.