Thumbnails

Creating thumbnails and posters

Thumbnails and posters can be created by starting a thumbnail job.

Create a thumbnail job

POST /item/(item-id)/thumbnail

Creates a new thumbnail job with the specified parameters. Note that a job cannot both create thumbnails at specified intervals and posters. Creating thumbnails according to transcoder rules and creating posters is however allowed.

Changed in version 5.0: For multi-layer PSD/PSB files, only a thumbnail of all layers flattened will be generated by default.

Query Parameters:
  • createThumbnails (boolean) –
    • true - Creates thumbnails according to default transcoder rules.
    • t1, ... - Thumbnails will be created on the specified, comma-separated, time codes.
    • false (default) - No thumbnails will be created.
  • createPosters (string) – A list of time codes to use for creating posters.
  • thumbnailWidth (integer) – The width of the thumbnails. If thumbnailWidth is specified, thumbnailHeight must also be specified.
  • thumbnailHeight (integer) – The height of the thumbnails. If thumbnailHeight is specified, thumbnailWidth must also be specified.
  • thumbnailPeriod (string) – Timecode string specifying the interval of the thumbnails. It should be a decimal integer when working with multi-page images/PDFs, meaning every N page(s).
  • posterWidth (integer) – The width of the posters.
  • posterHeight (integer) – The height of the posters.
  • posterFormat (string) –
    • jpeg (default) - Creates posters in JPEG format.
    • png - Creates posters in PNG format.
  • thumbnailService (string) – Identifies which thumbnail resource that should be used.
  • tag (string) – Include additional video settings from this transcode preset. Resolution settings in the tag are overridden by query parameters thumbnailHeight and thumbnailWidth.
  • version (integer) – A version number. For creating thumbnails for older versions of the item essence. Default is latest version.
  • sourceTag (string) – Comma-separated shape tags. The fist valid shape will be chosen as the source of the job. If non of the tags are valid, the original shape will be used.
  • resourceId (string) – The transcoder resource to use to execute the job.
  • resourceTag (string) –

    New in version 25.2.

    The resource tag criteria used to select transcoders for the job.

    Boolean operators - AND, OR, NOT - are supported.

    Examples: resourceTag=location:stockholm,

    resourceTag=location:stockhom OR location:berlin,

    resourceTag=(location:stockhom OR location:berlin) AND (type:blue OR NOT type:red).

  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Produces:
Role:

_job_write

Example

Creating thumbnails according to transcoder rules and posters at the time codes 50@PAL and 100@PAL.

POST /item/VX-123/thumbnail?createThumbnails=true&createPosters=50@PAL,100@PAL&sourceTag=mov,mp4

<JobDocument xmlns="http://xml.vidispine.com/schema/vidispine">
   <jobId>VX-1219</jobId>
   <user>admin</user>
   <started>2010-04-23T11:24:24.434+02:00</started>
   <status>READY</status>
   <type>THUMBNAIL</type>
   <priority>MEDIUM</priority>
</JobDocument>

Item thumbnail resources

The following requests deal with managing thumbnail resources for specific items.

List thumbnail resources for an item

GET /item/(item-id)/thumbnailresource

Return one or more poster resource URIs which can be used to manage the thumbnails for a specific item.

Query Parameters:
  • version (integer) – Return thumbnails from this essence version. By default thumbnails for the latest version will be returned.
Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/json – URIListDocument of thumbnail resource URIs
GET /item/(item-id)/posterresource

Return one or more poster resource URIs which can be used to manage the posters for a specific item.

Query Parameters:
  • version (integer) – Return posters from this essence version. By default posters for the latest version will be returned.
Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/json – URIListDocument of thumbnail resource URIs

Update or create a thumbnail resource for an item

PUT /item/(item-id)/thumbnailresource

If no thumbnail resources are defined for an item, create a resource and return it. Otherwise, return the existing resource.

Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/json – URIListDocument of thumbnail resource URIs
PUT /item/(item-id)/posterresource

If no poster resources are defined for an item, create a resource and return it. Otherwise, return the existing resource.

Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/json – URIListDocument of thumbnail resource URIs

Note

Thumbnails and posters for an item share the same resource. Hence, if a resource is added for posters, it is automatically added for thumbnails as well.

Get a thumbnail sprite sheet for an item

New in version 5.6.

A thumbnail sprite sheet is a large image containing all of the thumbnails for an item, together with information about each thumbnail.

GET /item/(item-id)/thumbnail/spritesheet

Returns a thumbnail sprite sheet which contains a URI to the generated sprite sheet and the positions of the images.

Query Parameters:
  • noauth-url (boolean) –
    • true Return URIs that do not need authentication.
    • false (default) Return normal URIs
Request Headers:
  • If-Modified-None – Optional header containing ETag of previous call. If no changes to thumbnails have been done, a 304 Not Modified is returned.
Response Headers:
  • ETag – Contains the computed ETag of the response.
Produces:
Role:

_thumbnail_read

Thumbnail resource handling

The following requests deal with managing collections of thumbnail URIs for a specific thumbnail resource.

List all thumbnails

GET {thumbnail-resource}

Returns thumbnail URIs on which further requests may be performed.

Query Parameters:
  • url (boolean) –
    • true - Return list of URLs.
    • false (default) - Return list of ids.
  • noauth-url (boolean) –
    • true Return URIs that do not need authentication.
    • false (default) Return normal URIs
Produces:
  • text/plain – CRLF-delimited list of thumbnail URIs.
  • application/xml, application/json – URIListDocument of thumbnail URIs
Role:

_thumbnail_read

Update or create a thumbnail

PUT {thumbnail-resource}/(time)

Create a new thumbnail at the specified time code. If a thumbnail with the specified time code already exists it is replaced.

Query Parameters:
  • setRepresentativeThumbnail (boolean) – Set to true to update the representativeThumbnail and representativeThumbnailNoAuth metadata fields. Default is false.
Accepts:
  • image/png, image/jpeg – Image to insert
Produces:
  • text/plain – Informational status message.
Status Codes:
  • 400 – Given data was not valid image/png or image/jpeg
Role:

_thumbnail_write
PUT {thumbnail-resource}/multi

Create multiple thumbnails at once. If a thumbnail with the specified time code already exists it is replaced.

Query Parameters:
  • setRepresentativeThumbnail (boolean) – Set to true to update the representativeThumbnail and representativeThumbnailNoAuth metadata fields. Default is false.
Accepts:
Role:

_thumbnail_write

Delete all thumbnails

DELETE {thumbnail-resource}

Remove all thumbnails handled by this resource.

Role:_thumbnail_write

Thumbnail handling

The following requests concern handling a specific thumbnail.

Retrieve the image representation

GET {thumbnail-resource}/(time)

Return the image representation of this thumbnail.

Query Parameters:
  • hash (string) – The checksum of the image.
  • type (string) – Optional type.
Produces:
  • image/png, image/jpeg – Image of the thumbnail
Role:

_thumbnail_read

Retrieve multiple thumbnails

GET {thumbnail-resource}/multi

Get multiple thumbnail at once.

Query Parameters:
  • from (string) – Optional, the minimum timecode of thumbnails/posters (lower bound).
  • to (string) – Optional, the maximum timecode of thumbnails/posters (upper bound).
Produces:
Role:

_thumbnail_read

Delete a thumbnail

DELETE {thumbnail-resource}/(time)

Remove this thumbnail.

Role:_thumbnail_write

Export a thumbnail

POST {thumbnail-resource}/(time)/export

Starts a job that writes the thumbnail or poster to a specific destination.

Query Parameters:
  • uri (string) – Required. URI of export location of thumbnail or poster
  • format (string) – Image format of destination. E.g. tiff.
  • notification (string) – The placeholder job notification to use for this job.
  • notificationData (string) – Any additional data to include for notifications on this job.
  • priority (string) – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata (string[]) – Additional information for the job task.
  • holdJob (boolean) – If set to true, the job will be created in a HOLD state. Default is false.
Produces:
Role:

_thumbnail_read