support Contact Support | system status System Status
Page Contents

    Thumbnails Settings

    This topic contains details for encoding settings related to video thumbnails.

    thumbnails

    thumbnails:Array or Hash

    API Versions: V1, V2

    Parent: outputs

    Compatible Job Types: All

    Example:

    • "thumbnails": [{}]
    • "thumbnails": {}

    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

    label:String

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Compatible Job Types: All

    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

    format:String

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: png

    Valid Values: png or jpg

    Compatible Job Types: All

    Example: jpg

    Description:

    The format of the thumbnail image.

    {
      "input": "s3://zencodertesting/test.mov",
      "outputs": [
        {
          "thumbnails": {
            "format": "jpg"
          }
        }
      ]
    }

    number

    number:Integer

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Valid Values: A positive integer

    Compatible Job Types: All

    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

    start_at_first_frame:Boolean

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    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

    interval:Float

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Compatible Job Types: All

    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

    interval_in_frames:Float

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Compatible Job Types: All

    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

    times:Array

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Compatible Job Types: All

    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

    aspect_mode:String

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: preserve

    Valid Values: preserve, stretch, crop, or pad

    Compatible Job Types: All

    Example: pad

    Description:

    The aspect mode to use when creating thumbnails.

    • preserve: By default, Zencoder will preserve the aspect ratio of the output video file, so if you submit widescreen content and ask for standard resolution, the thumbnail file will keep the widescreen aspect ratio, and will fit within the requested size.
    • stretch: When the aspect mode is "stretch", the thumbnail will exactly match the requested width and height, even if it distorts the image.
    • crop: This option tells Zencoder to "zoom in" to the thumbnail to match the requested size, by cropping pixels from the top/bottom or left/right.
    • pad: The pad option tells Zencoder to letterbox the thumbnail to match the requested frame size. Use this option to maintain the aspect ratio of the output video, but always get thumbnails of the same size.

    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
          }
        }
      ]
    }

    See Also: size, width, and height

    size

    size:String

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Compatible Job Types: All

    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

    width:Integer

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Valid Values: A positive integer

    Compatible Job Types: All

    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

    height:Integer

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Valid Values: A positive integer

    Compatible Job Types: All

    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

    base_url:String

    API Versions: V1, 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: All

    Example:

    • s3://my-output-bucket/
    • cf://username:api_key@container/path/
    • ftp://user:password@ftp.example.com/path/to

    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/"
          }
        }
      ]
    }

    See Also: prefix and filename

    prefix

    prefix:String

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: frame

    Compatible Job Types: All

    Example:

    • thumbs
    • video_thumbnails

    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"
          }
        }
      ]
    }

    See Also: base_url and filename

    filename

    filename:String

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: frame

    Compatible Job Types: All

    Example:

    • thumbnail_{{number}}
    • {{number}}_{{width}}x{{height}}-thumbnail

    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"
          }
        }
      ]
    }

    See Also: base_url and prefix

    public

    public:Boolean

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    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

    access_control:Array

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Valid Values: An array of hashes containing two settings: grantee and permission.

    Compatible Job Types: All

    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

    grantee:String

    API Versions: V1, V2

    Parent: outputs / thumbnails / access_control

    Valid Values: A valid S3 grantee (email, ID, or URI)

    Compatible Job Types: All

    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

    permission:String

    API Versions: V1, 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: All

    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

    rss

    rrs:Boolean

    API Versions: V1, V2

    Parent: outputs / thumbnails

    Default: false

    Valid Values: true or false

    Compatible Job Types: All

    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

    headers:Hash

    API Versions: V1, V2

    Parents: outputs OR thumbnails

    Compatible Job Types: All

    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

    credentials:String

    API Versions: V2

    Parent: outputs / thumbnails

    Compatible Job Types: All

    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

    parallel_upload_limit:Integer

    API Versions: V1, V2

    Default: 30 for S3, 10 for all other destinations.

    Valid Values: An integer between 1 and 30

    Compatible Job Types: All

    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
          }
        }
      ]
    }

    Page last updated on 06 Apr 2020