thumbnails:Array or Hash
API Versions: V2
Parent: outputs
Compatible Job Types: VOD
Example:
Description:
For every output, you can ask for one or more thumbnails.
Each output can have its own sets of thumbnails with unique size, base_url, and access_control set.
Multiple sets of thumbnails can be created for a single output by passing multiple thumbnail hashes within an array. If thumbnail options are passed in an array, a label must be set for set.
Set S3 access_control using the same options as you use for output videos.
Thumbnails are limited to 100 per-set. If more thumbnails would be generated given the options requested a warning will be added to the output and creation of thumbnails will stop when the limit is reached.
Note: There is no such thing as a thumbnail-only job. Specifying an output with just thumbnails will also create a billable, full-length mp4 with our default transcoding settings and upload it to temporary storage.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": [
{
"label": "first",
"number": 10
},
{
"label": "second",
"interval_in_frames": 5000
}
]
}
]
}
See Also: label
label:String
API Versions: V2
Parent: outputs / thumbnails
Compatible Job Types: VOD
Example: poster
Description:
A name for the thumbnail set. Required when requesting thumbnail sets in an array.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": [
{
"label": "poster"
},
{
"label": "clips"
}
]
}
]
}
format:String
API Versions: V2
Parent: outputs / thumbnails
Default: png
Valid Values: png or jpg
Compatible Job Types: VOD
Example: jpg
Description:
The format of the thumbnail image.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"format": "jpg"
}
}
]
}
number:Integer
API Versions: V2
Parent: outputs / thumbnails
Valid Values: A positive integer
Compatible Job Types: VOD
Example: 3
Description:
A number of thumbnails to capture. Zencoder will grab evenly-spaced thumbnails across the whole duration of the file. So if you ask for 1 thumbnail, it will be near the middle of the file. Specifying 3 thumbnails on a 8 minute video will result in thumbnails at approximately 2, 4, and 6 minutes.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"number": 3
}
}
]
}
start_at_first_frame:Boolean
API Versions: V2
Parent: outputs / thumbnails
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Example: true
Description:
When using the number option for thumbnail generation this will begin taking thumbnails with the first frame.
For example, when using if your video is 5 seconds long and you request 5 thumbnails using the number option, this will create thumbnails at 0s, 1s, 2s, 3s, and 4s. Normally it would grab thumbnails at 0.83s, 1.66s, 2.49s, 3.32s, and 4.15s.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"number": 5,
"start_at_first_frame": true
}
}
]
}
interval:Float
API Versions: V2
Parent: outputs / thumbnails
Compatible Job Types: VOD
Example: 60
Description:
Take thumbnails at an even interval, in seconds. Zencoder will return one thumbnail for every N seconds of the file. So if you choose an interval of 60, and your input file is 12 minutes long, you’ll get back 12 thumbnails, each one on the minute.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"interval": 60
}
}
]
}
See Also: interval_in_frames
interval_in_frames:Float
API Versions: V2
Parent: outputs / thumbnails
Compatible Job Types: VOD
Example: 120
Description:
Take thumbnails at an even interval, in frames. Zencoder will return one thumbnail for every N frames of the file. So if you choose an interval of 120, and your input file is 29.97 frames per second, you’ll get back thumbnails for approximately every 4 seconds.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"interval_in_frames": 120
}
}
]
}
See Also: interval
times:Array
API Versions: V2
Parent: outputs / thumbnails
Compatible Job Types: VOD
Example: [0, 30, 60, 90]
Description:
An array of times, in seconds, at which to grab a thumbnail. Decimals are valid. So setting times to [12.5, 25] would grab two thumbnails, one at 12.5 seconds, and one at 25 seconds. This value must be an array of non-negative numbers.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"times": [0, 30, 60, 90]
}
}
]
}
aspect_mode:String
API Versions: V2
Parent: outputs / thumbnails
Default: preserve
Valid Values: preserve, stretch, crop, or pad
Compatible Job Types: VOD
Example: pad
Description:
The aspect mode to use when creating thumbnails.
Note: Due to the constraints of video scaling algorithms the dimensions of the thumbnails will be an even number. If you request thumbnails at 100x75, for example, you will get thumbnails that are 100x74.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"aspect_mode": "pad",
"width": 200,
"height": 200
}
}
]
}
size:String
API Versions: V2
Parent: outputs / thumbnails
Compatible Job Types: VOD
Example: 400x300
Description:
A target resolution for the thumbnails, like "160×120″. If no size is provided, thumbnails will be the same size as the output video. By default, we will preserve aspect ratio, so if the aspect ratio of this size parameter does not match the aspect ratio of the movie, the resulting file may not exactly match this size. If Stretch is set to true for the corresponding output file, then this thumbnail will also be stretched to fill the resolution.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"size": "400x300"
}
}
]
}
See Also: width, height, and aspect_mode
width:Integer
API Versions: V2
Parent: outputs / thumbnails
Valid Values: A positive integer
Compatible Job Types: VOD
Example: 640
Description:
Thumbnail width. If no width is supplied, we will use the output file width, or scale to size or height setting.
Note that size takes priority over either width and height.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"width": 640
}
}
]
}
See Also: size, height, and aspect_mode
height:Integer
API Versions: V2
Parent: outputs / thumbnails
Valid Values: A positive integer
Compatible Job Types: VOD
Example: 480
Description:
Thumbnail height. If no height is supplied, we will use the output file height, or scale to size or width setting.
Note that size takes priority over either width and height.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"height": 480
}
}
]
}
See Also: size, width, and aspect_mode
base_url:String
API Versions: V2
Parent: outputs / thumbnails
Valid Values: A valid S3, Cloud Files, GCS, FTP, FTPS, or SFTP URL, minus filename. Format: s3://[bucket name]/[path] or ftp://[user]:[password]@[ftp.url]/[path]
Compatible Job Types: VOD
Example:
Description:
An output destination for thumbnails. If base_url is blank, we will store thumbnails in our Zencoder S3 bucket. Files stored in the Zencoder S3 bucket will be available after 24 hours. Note that the filenames are not unique between outputs (e.g. frame_0000.png), so the destination should be a unique directory or key prefix to avoid overwriting files.
FTP users: we try to write from the root of your server, so use an absolute path for your URL to ensure that we can write to your server successfully.
Notes on Credentials:
If you provide credentials via base_url they will be present in the urls appearing in requests to the job details, output details, etc. If credentials are stored with Zencoder they will not appear in urls in those responses.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"base_url": "s3://my-output-bucket/"
}
}
]
}
prefix:String
API Versions: V2
Parent: outputs / thumbnails
Default: frame
Compatible Job Types: VOD
Example:
Description:
Thumbnail files will be exported with sequential filenames. However, you may specify a custom prefix for the thumbnail files. If no prefix is specified we’ll use frame. For example, if you use the prefix 'custom', the files exported would be named custom_0000.png, custom_0001.png, etc. Without a custom prefix they would be named frame_0000.png, frame_0001.png, etc.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"prefix": "thumbs"
}
}
]
}
filename:String
API Versions: V2
Parent: outputs / thumbnails
Default: frame
Compatible Job Types: VOD
Example:
Description:
Thumbnail files can be given a filename based on several attributes. Attributes include number, padded-number, width, height, and size. It is not necessary to add a file extension, as it will be added by Zencoder based on the “format” option.
number or padded-number must be used, all others are optional. padded-number uses 4 spots (0000, 0001, etc).
height, width, and size will be based on the actual size of the generated thumbnail.
Example: _x-thumbnail
Valid characters include letters, numbers, dashes, underscores, and the interpolated values.
Note: If you specify a filename, any specified prefix will be ignored.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"filename": "_x-thumbnail"
}
}
]
}
public:Boolean
API Versions: V2
Parent: outputs / thumbnails
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Description:
The same as public for output files. See public for full documentation of this option.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"number": 10,
"public": true
}
}
]
}
See Also: access_control
access_control:Array
API Versions: V2
Parent: outputs / thumbnails
Valid Values: An array of hashes containing two settings: grantee and permission.
Compatible Job Types: VOD
Description:
The same as access_control for output files. See access_control for full documentation of this option.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"access_control": [
{
"permission": "READ",
"grantee": "someone@example.com"
}
]
}
}
]
}
See Also: public, grantee, and permission
grantee:String
API Versions: V2
Parent: outputs / thumbnails / access_control
Valid Values: A valid S3 grantee (email, ID, or URI)
Compatible Job Types: VOD
Description:
The same as grantee for output files. See grantee for full documentation of this option.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"access_control": [
{
"permission": "FULL_CONTROL",
"grantee": "cdc7931a9574b1055d5b76112021d0e9"
}
]
}
}
]
}
See Also: access_control and permission
permission:String
API Versions: V2
Parent: outputs / thumbnails / access_control
Valid Values: A string or array of strings containing: READ, READ_ACP, WRITE_ACP, or FULL_CONTROL
Compatible Job Types: VOD
Description:
The same as permission for output files. See permission for full documentation of this option.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"access_control": [
{
"permission": "FULL_CONTROL",
"grantee": "cdc7931a9574b1055d5b76112021d0e9"
}
]
}
}
]
}
See Also: access_control and grantee
rrs:Boolean
API Versions: V2
Parent: outputs / thumbnails
Default: false
Valid Values: true or false
Compatible Job Types: VOD
Description:
The same as rrs for output files. See rrs for full documentation of this option.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"rrs": true
}
}
]
}
headers:Hash
API Versions: V2
Parents: outputs OR thumbnails
Compatible Job Types: VOD
Example: { "Content-Type": "binary/octet-stream" }
Description:
HTTP headers to send with your thumbnails when we upload them. This feature is currently supported when using S3 and Cloud Files.
Zencoder supports setting a limited subset of these headers: Cache-Control, Content-Disposition, Content-Encoding, Content-Type, Expires, x-amz-acl, x-amz-storage-class, x-amz-server-side-encryption, and x-amz-meta-*.
Headers will be ignored when an output location is not specified.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"headers": {
"Content-Type": "binary/octet-stream",
"x-amz-acl": "public-read-write"
}
}
}
]
}
credentials:String
API Versions: V2
Parent: outputs / thumbnails
Compatible Job Types: VOD
Example: ftp_dev_server
Description:
References the nickname of saved credentials to use for transfer, which are managed in the Account Credentials section.
NOTE: Credentials for syndication services are for output videos only.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"base_url": "ftp://ftp.example.com/thumbnails/",
"credentials": "ftp_dev_server"
}
}
]
}
See Also: base_url
parallel_upload_limit:Integer
API Versions: V2
Default: 30 for S3, 10 for all other destinations.
Valid Values: An integer between 1 and 30
Compatible Job Types: VOD
Example: 5
Description:
The maximum number of simultaneous uploads made when uploading thumbnails.
This may speed up transfer times, depending on the bandwidth at your remote server. Be aware that more connections can place a heavier load on the server. If you have trouble with upload timeouts, or want to prevent Zencoder from using too much bandwidth when uploading files, set this to 1.
{
"input": "s3://zencodertesting/test.mov",
"outputs": [
{
"thumbnails": {
"base_url": "ftp://ftp.example.com/thumbnails/",
"parallel_upload_limit": 5
}
}
]
}