Thumbnails

Creating thumbnails and posters

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

Start 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.

Query Parameters:
 
  • createThumbnails
    • 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 – An optional list of time codes to use for creating posters.
  • thumbnailWidth – An optional integer specifying the width of the thumbnails.
  • thumbnailHeight – An optional integer specifying the height of the thumbnails.
  • thumbnailPeriod – An optional 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 – An optional integer specifying the width of the posters.
  • posterHeight – An optional integer specifying the height of the posters.
  • posterFormat
    • jpeg (default) - Creates posters in JPEG format.
    • png - Creates posters in PNG format.
  • thumbnailService – An optional identifier to which thumbnail resource that should be used.
  • tag – Include additional video settings from this transcode preset.
  • version – An optional version number. For creating thumbnails for older versions of the item essence. Default is latest version.
  • sourceTag

    Optional 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.

    New in version 4.2.3.

  • resourceId

    The transcoder resource to use to execute the transcode.

    New in version 4.13.

  • notification – The placeholder job notification to use for this job. (Optional)
  • notificationData – Any additional data to include for notifications on this job. (Optional)
  • priority – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata – Additional information for the job task.
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.

Get 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 – 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/jsonURIListDocument of thumbnail resource URIs

New in version 4.2.

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 – 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/jsonURIListDocument of thumbnail resource URIs

Put resources for an item

PUT /item/(item-id)/thumbnailresource

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

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

New in version 4.2.

PUT /item/(item-id)/posterresource

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

Produces:
  • text/plain – CRLF-delimited list of thumbnail resource URIs
  • application/xml, application/jsonURIListDocument 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.

Thumbnail resource handling

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

Get list of thumbnails

GET {thumbnail-resource}

Returns thumbnail URIs on which further requests may be performed.

Query Parameters:
 
  • url
    • true - Return list of URLs.
    • false (default) - Return list of ids.
  • noauth-url
    • 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/jsonURIListDocument of thumbnail URIs
Role:

_thumbnail_read

Insert or update 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.

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

Remove 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.

Get image representation

GET {thumbnail-resource}/(time)

Return the image representation of this thumbnail.

Produces:
  • image/png, image/jpeg – Image of the thumbnail
Role:

_thumbnail_read

Remove thumbnail

DELETE {thumbnail-resource}/(time)

Remove this thumbnail.

Role:_thumbnail_write

Export thumbnail

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

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

Query Parameters:
 
  • uri – Mandatory URI of export location of thumbnail or poster
  • format – Optional image format of destination. E.g. tiff.
  • notification – The placeholder job notification to use for this job. (Optional)
  • notificationData – Any additional data to include for notifications on this job. (Optional)
  • priority – The priority to assign to the job. Default is MEDIUM .
  • jobmetadata – Additional information for the job task.
Produces:
Role:

_thumbnail_read