Generate thumbnails

Generate thumbnails from a video Source with an SDK.

Generate images for posters, preview cards, or timeline previews from a video Source. You do not need to create an Asset or transcode first.

Video Assets already include a poster and timeline previews. Use this guide to generate thumbnails directly from a Source, or see Asset outputs to add thumbnails to an existing Asset.

Before you begin

You need a video Source in the same Project, a Project access token, and an official SDK. Replace the example token and Source ID. Keep the token on your server.

Use an existing Source, create one from a hosted file, or upload a video.

The example uses the Project's default output storage. For lasting files, configure your own storage and choose a distinct output path each time you generate thumbnails. Here, thumbnails/video-123/thumb-%05d.jpg is relative to the storage's base_prefix.

Generate thumbnails

This example generates ten individual JPEG images across the video. The default size is 320 pixels on the longest edge, preserving the aspect ratio without upscaling.

import Chunkify from '@chunkify/chunkify';

async function main() {
    const client = new Chunkify({
        projectAccessToken: 'My Project Access Token',
    });

    const thumbnail = await client.thumbnails.create({
        source_id: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
        count: 10,
        storage: {
            path: 'thumbnails/video-123/thumb-%05d.jpg',
        },
    });

    console.log(thumbnail.id, thumbnail.status);
}

main().catch((error) => {
    console.error(error);
    process.exitCode = 1;
});
from chunkify import Chunkify

client = Chunkify(
    project_access_token="My Project Access Token",
)

thumbnail = client.thumbnails.create(
    source_id="src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
    count=10,
    storage={
        "path": "thumbnails/video-123/thumb-%05d.jpg",
    },
)

print(thumbnail.id, thumbnail.status)
<?php

use Chunkify\Client;

require_once __DIR__ . '/vendor/autoload.php';

$client = new Client(
    projectAccessToken: 'My Project Access Token',
);

$thumbnail = $client->thumbnails->create(
    sourceID: 'src_2G6MJiNz71bHQGNzGwKx5cJwPFS',
    count: 10,
    storage: [
        'path' => 'thumbnails/video-123/thumb-%05d.jpg',
    ],
);

var_dump($thumbnail->id, $thumbnail->status);
package main

import (
	"context"
	"fmt"
	"log"

	"github.com/chunkifydev/chunkify-go"
	"github.com/chunkifydev/chunkify-go/option"
)

func main() {
	client := chunkify.NewClient(
		option.WithProjectAccessToken("My Project Access Token"),
	)

	thumbnail, err := client.Thumbnails.New(
		context.Background(),
		chunkify.ThumbnailNewParams{
			SourceID: "src_2G6MJiNz71bHQGNzGwKx5cJwPFS",
			Count:    chunkify.Int(10),
			Storage: chunkify.ThumbnailCreateStorageParam{
				Path: chunkify.String("thumbnails/video-123/thumb-%05d.jpg"),
			},
		},
	)
	if err != nil {
		log.Fatal(err)
	}

	fmt.Println(thumbnail.ID, thumbnail.Status)
}

The response includes a thm_ ID. Save it to match webhook notifications. Generation runs asynchronously; the images are available once status is ready.

Choose when to capture thumbnails

Use exactly one sampling option:

Option	Behavior
`count`	Choose 1 to 100 thumbnails, one from the middle of each equal section of the selected range.
`timestamps`	Choose 1 to 100 specific times in seconds, such as `[5, 15, 30]`.

For example, count: 3 on a 60-second video targets 10, 30, and 50 seconds. To use specific times, replace count with timestamps.

By default, sampling covers the whole Source. Set range.start and range.end to limit it. Times are always relative to the original Source, including when you select a range. The start is included and the end is excluded; every selected timestamp must fall within those bounds.

Choose the output

Choose individual images for posters or preview cards, or sprite sheets to combine timeline thumbnails into fewer files. Both layouts include a WebVTT index that maps video times to images and, for sprites, their positions within each sheet.

Setting	Options
`output`	`images` for individual files, or `sprites` for automatically arranged sprite sheets. Defaults to `images`.
`format`	`jpeg` or `webp`. Defaults to `jpeg`.
`size`	Maximum image or sprite-tile edge, from 64 to 1920 pixels. Defaults to 320.

Images preserve the video's aspect ratio without cropping or upscaling. The size applies to each thumbnail, not the complete sprite sheet.

For customer storage, storage.path must contain one %05d placeholder and end in .jpg for JPEG or .webp for WebP. Chunkify replaces the placeholder with the image or sheet number, starting at 1. The example above produces filenames such as thumb-00001.jpg, plus thumb.vtt for the timeline index.

See Create Thumbnails for all request settings.

Get the result

Subscribe to thumbnail.ready and thumbnail.failed through a verified webhook so your application is notified when processing finishes.

On success, files lists the images or sprite sheets and the WebVTT index, while samples describes the frames produced.

Continue with Outputs and lifecycle for webhook details and file URLs.

Pricing

Additional thumbnails are charged per published sample, including each thumbnail inside a sprite sheet. See thumbnail pricing and output transfer costs. The default Asset poster and timeline previews are included in streaming preparation.