Thumbnails

Transcodely can generate thumbnails from your video alongside transcoding outputs. Thumbnails are configured at the job level and support multiple extraction modes — from a single poster frame to sprite sheets for video scrubbing.

Thumbnails are configured in the thumbnails array of a Create Job request. Each job supports up to 5 thumbnail specifications.

Thumbnails add a 1.10x feature multiplier to the job cost. See Pricing for details.

The ThumbnailSpec object

Attribute	Type	Required	Description
`mode`	enum	Yes	Extraction mode. One of: `single`, `interval`, `sprite`, `timestamps`. See Modes.
`format`	enum	No	Image format. One of: `jpeg`, `png`, `webp`. Default: `jpeg`. See Formats.
`width`	integer	No	Output width in pixels (16—3840). If only `width` is set, height is calculated to maintain aspect ratio.
`height`	integer	No	Output height in pixels (16—2160). If only `height` is set, width is calculated to maintain aspect ratio.
`quality`	integer	No	Image quality (1—100). Default: `80`. Applies to JPEG and WebP. Ignored for PNG.
`timestamp`	number	No	Time in seconds to extract the frame. Only valid for `single` mode. Default: `0`.
`interval_seconds`	number	No	Interval between frames in seconds (0.5—300). Required for `interval` and `sprite` modes.
`timestamps`	array of numbers	No	Specific timestamps in seconds to extract. Required for `timestamps` mode.
`sprite_columns`	integer	No	Number of columns in the sprite sheet (1—20). Only valid for `sprite` mode. Default: `10`.

{
  "mode": "single",
  "format": "jpeg",
  "width": 1280,
  "height": 720,
  "quality": 90,
  "timestamp": 5.0
}

Modes

Each thumbnail spec requires a mode that determines how frames are extracted from the video.

Mode	API Value	Description	Output
Single	`single`	Extract a single frame at a specific timestamp. Use for poster images, social media thumbnails, or preview images.	One image file.
Interval	`interval`	Extract frames at regular intervals throughout the video. Use for storyboard generation or content review.	Multiple image files.
Sprite	`sprite`	Combine interval-extracted frames into a single sprite sheet image. Use for video scrubbing / seek preview in players.	One sprite sheet image + WebVTT file.
Timestamps	`timestamps`	Extract frames at specific timestamps. Use when you need frames at exact moments (scene changes, chapter markers).	Multiple image files.

Formats

Format	API Value	Best For	Notes
JPEG	`jpeg`	General use, poster images	Lossy compression. Smallest file size. `quality` parameter applies. Default.
PNG	`png`	Screenshots, UI overlays	Lossless compression. Larger files. `quality` parameter is ignored.
WebP	`webp`	Web delivery	Lossy compression with better quality-to-size ratio than JPEG. `quality` parameter applies.

Sprite sheets

Sprite sheets combine multiple thumbnails into a single image in a grid layout, paired with a WebVTT file that maps each thumbnail to its timecode. Video players use this for seek preview (showing a thumbnail when the user hovers over the progress bar).

sprite_columns controls the number of columns in the grid. Rows are calculated automatically based on the total number of frames and columns.

For a 2-minute video with interval_seconds: 10 and sprite_columns: 5:

12 frames extracted (one every 10 seconds)
Grid: 5 columns x 3 rows (15 slots, 12 filled)
Output: 1 sprite sheet image + 1 WebVTT file

The generated WebVTT file maps each frame to its position in the sprite sheet:

WEBVTT

00:00:00.000 --> 00:00:10.000
sprite.jpg#xywh=0,0,320,180

00:00:10.000 --> 00:00:20.000
sprite.jpg#xywh=320,0,320,180

00:00:20.000 --> 00:00:30.000
sprite.jpg#xywh=640,0,320,180

Examples

Single poster frame

Extract a poster image at the 5-second mark.

{
  "thumbnails": [
    {
      "mode": "single",
      "format": "jpeg",
      "width": 1280,
      "height": 720,
      "quality": 90,
      "timestamp": 5.0
    }
  ]
}

Interval thumbnails

Extract a thumbnail every 30 seconds for content review.

{
  "thumbnails": [
    {
      "mode": "interval",
      "format": "jpeg",
      "width": 640,
      "height": 360,
      "quality": 80,
      "interval_seconds": 30
    }
  ]
}

Sprite sheet for video scrubbing

Generate a sprite sheet for seek preview in your video player.

{
  "thumbnails": [
    {
      "mode": "sprite",
      "format": "jpeg",
      "width": 320,
      "height": 180,
      "quality": 70,
      "interval_seconds": 10,
      "sprite_columns": 10
    }
  ]
}

Specific timestamps

Extract frames at chapter markers or scene changes.

{
  "thumbnails": [
    {
      "mode": "timestamps",
      "format": "webp",
      "width": 1920,
      "height": 1080,
      "quality": 85,
      "timestamps": [0, 15.5, 45.0, 120.0, 300.0, 600.0]
    }
  ]
}

Multiple thumbnail specs in one job

Combine a poster frame and a sprite sheet in a single job.

{
  "thumbnails": [
    {
      "mode": "single",
      "format": "jpeg",
      "width": 1920,
      "height": 1080,
      "quality": 95,
      "timestamp": 10.0
    },
    {
      "mode": "sprite",
      "format": "jpeg",
      "width": 320,
      "height": 180,
      "quality": 70,
      "interval_seconds": 5,
      "sprite_columns": 10
    }
  ]
}

Complete job example

A full Create Job request with HLS outputs, a poster frame, and a sprite sheet for seek preview.

{
  "input_url": "gs://my-bucket/uploads/video.mp4",
  "output_origin_id": "ori_x9y8z7w6v5",
  "outputs": [
    {
      "type": "hls",
      "video": [
        {"codec": "h264", "resolution": "1080p", "quality": "standard"},
        {"codec": "h264", "resolution": "720p", "quality": "standard"},
        {"codec": "h264", "resolution": "480p", "quality": "economy"}
      ]
    }
  ],
  "thumbnails": [
    {
      "mode": "single",
      "format": "jpeg",
      "width": 1280,
      "height": 720,
      "quality": 90,
      "timestamp": 5.0
    },
    {
      "mode": "sprite",
      "format": "jpeg",
      "width": 320,
      "height": 180,
      "quality": 70,
      "interval_seconds": 10,
      "sprite_columns": 10
    }
  ],
  "priority": "standard"
}

Validation rules

Transcodely validates thumbnail configuration at job creation time. The following constraints are enforced:

Rule	Description
Maximum 5 specs	Each job supports up to 5 `thumbnails` entries.
Mode required	Every thumbnail spec must have a `mode` set.
`timestamp` requires `single`	The `timestamp` field is only valid when `mode` is `single`.
`interval_seconds` required for `interval` / `sprite`	The `interval_seconds` field must be set when `mode` is `interval` or `sprite`.
`timestamps` required for `timestamps` mode	The `timestamps` array must be non-empty when `mode` is `timestamps`.
`sprite_columns` requires `sprite`	The `sprite_columns` field is only valid when `mode` is `sprite`.
Dimension range	`width` must be 16—3840. `height` must be 16—2160.
Quality range	`quality` must be 1—100.
Interval range	`interval_seconds` must be 0.5—300.
Sprite columns range	`sprite_columns` must be 1—20.
Timestamps non-negative	All values in `timestamps` must be >= 0.

#Thumbnails

#The ThumbnailSpec object

#Modes

#Formats

#Sprite sheets

#Examples

#Single poster frame

#Interval thumbnails

#Sprite sheet for video scrubbing

#Specific timestamps

#Multiple thumbnail specs in one job

#Complete job example

#Validation rules