Thumbnail Capture

Capture thumbnails from your source video.

To generate thumbnail images, please specify a separate encoding task using thumbnail output format.

<?xml version="1.0"?>
<query>
    <userid>[UserID]</userid> {/* required*/}
    <userkey>[UserKey]</userkey> {/* required*/}
    <action>[Action]</action> {/* required*/}
    <source>[SourceFile]</source> {/* required*/}
    <format>
        <output>thumbnail</output> {/* required*/}
        <time>[Time]</time>
        <width>[Width]</width>
        <height>[Size]</height>
        <scale_mode>[pad|stretch|fit|cover|center]</scale_mode>
        <allow_upscale>[yes|no]</allow_upscale>
        <size_divisible_by>[N]</size_divisible_by>
        <use_vtt>[yes|no]</use_vtt>
        <vtt_line_size>[LineSize]</vtt_line_size>
        <vtt_max_lines>[MaxLinesPerTile]</vtt_max_lines>
        <vtt_destination>[VTTDestination]</vtt_destination>
        <public_url>[PublicURL]</public_url>
        <public_vtt_url>[VTTManifestPublicURL]</public_vtt_url>
        <quality>[Quality]</quality>
        <destination>[DestFile]</destination>
        {/* Format params */}
    </format>
</query>
{
    "query": {
        "userid": "[UserID]", // required
        "userkey": "[UserKey]", // required
        "action": "[Action]", // required
        "source": "[SourceFile]", // required
        "format": {
            "output": "thumbnail", // required
            "time": "[Time]",
            "width": "[Width]",
            "height": "[Size]",
            "scale_mode": "[pad|stretch|fit|cover|center]",
            "allow_upscale": "[yes|no]",
            "size_divisible_by": "[N]",
            "use_vtt": "[yes|no]",
            "vtt_line_size": "[LineSize]",
            "vtt_max_lines": "[MaxLinesPerTile]",
            "vtt_destination": "[VTTDestination]",
            "public_url": "[PublicURL]",
            "public_vtt_url": "[VTTManifestPublicURL]",
            "quality": "[Quality]",
            "destination": "[DestFile]"
        }
    }
}
ParameterDescriptionAllowed ValuesDefault Value
timeSpecify the timestamp in seconds, percentage, or interval to capture thumbnails.hh:mm:ss.ms – once created thumbnail from given timestamp.
Example:

N% – Positive percentage number from 1 to 100%.
Will generate thumbnail on N% of video duration.
Example:

N – Positive number greater than 0.01.
Will generate thumbnail on N second.
Example:

N! – Positive integer number greater or equals to 1.
Will generate thumbnail on every N second.
Example:
5
widthSpecify the thumbnail width in pixels.Positive integernone
heightSpecify the thumbnail height in pixels.Positive integernone
scale_modeSpecifies how the picture fits into width and height.
pad – keep the aspect ratio and pad the picture, same as keep_aspect_ratio=yes.
stretch – scale the picture to width and height, same as keep_aspect_ratio=no.
fit – keep the aspect ratio without padding: the image fits within width and height, e.g. a square video in 210x158 gives 158x158.
cover – keep the aspect ratio and fill width and height, the overflow is cropped evenly from both sides.
center – no scaling: the picture is centered, cropped or padded to width and height.
pad, stretch, fit, cover, centerpad
allow_upscaleWhen no, the picture is never scaled up: a source smaller than the size keeps its size with fit and cover or is padded to the size without scaling with pad. Can't be used with stretch.yes, noyes
size_divisible_byWidth and height calculated by fit or from width or height only are rounded to the nearest multiple of this value, never above the size.Even integer from 2 to 642
use_vttEnable merging of thumbnails in single video tooltip thumbnail (VTT).yes, nono
vtt_line_sizeSpecify the number of thumbnails used for the VTT image.Positive integer4
vtt_max_linesSpecify the maximum count of lines per tile. In cases where more than one tile is needed than a set of tiles is generated.Positive integernone
vtt_destinationSpecify the VTT manifest file destination.Valid URLnone
public_urlSpecify the public URL to use in VTT manifest to point to tiles.Valid URLnone
public_vtt_urlSpecify the public URL to VTT manifest file.Valid URLnone
qualityImage QualityPositive integer between 1 and 10083
📘

Note

JPEG is the only supported image format for thumbnail images.

🚧

Note

If your specified thumbnail width and height are different from your video's aspect ratio, you may get black spaces added to the thumbnail image. Use scale_mode=fit to keep the video aspect ratio without them.

If you specify only width or height, the other will be calculated according to your video size.

If neither width nor height are specified, the thumbnail will result in the same size as your video.