#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 are free — they’re bundled with the transcoding cost and add no feature multiplier. See Pricing for details.

#The ThumbnailSpec object

{
  "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.

#Formats

jpeg and png are invalid for animated mode. Animated previews always emit a WebP loop (format: "webp") plus a muted MP4 loop; the MP4’s result carries the free-form format: "mp4" (it is not a ThumbnailFormat enum value). See Animated previews for the WebP 10-second cap.

#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

#Animated previews

Animated mode produces short hover-preview loops for card and grid UIs. Like every thumbnail mode it is free — it adds no cost to the job.

By default the worker produces both an animated WebP and a muted MP4 loop from the same samples, so a consumer can pick whichever its surface supports. Set format: "webp" to emit only the WebP.

Deterministic sampling. Unless start_offsets is set, clips are taken at fixed 25% / 50% / 75% marks of the source duration — no scene detection. Provide up to three start_offsets (seconds from the source start) to override those marks; the worker clamps each to the source duration.

Smart defaults (applied worker-side; the API stores exactly what you send): 4 s duration_seconds, 12 fps, 320 px width.

The 10-second WebP cap. The animated WebP is hard-capped at 10 seconds. When duration_seconds exceeds 10, the WebP is skipped and the output is MP4-only — documented behavior, not an error. The exception: if you set format: "webp" explicitly, a duration_seconds above 10 is rejected at job creation instead.

Valid config for this mode: width, height, quality (WebP encode quality), duration_seconds, fps, start_offsets, and path_template. The single / interval / sprite / timestamps fields (timestamp, interval_seconds, timestamps, sprite_columns) are not valid here.

{
  "mode": "animated",
  "width": 320,
  "duration_seconds": 4,
  "fps": 12,
  "start_offsets": [3.0, 7.5, 12.0]
}

Results surface in thumbnail_results with mode: "animated" — one entry with format: "webp" (the WebP loop) and one with format: "mp4" (the muted MP4 loop). See Thumbnail results.

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

#Animated hover previews

Generate a 320 px hover-preview loop — an animated WebP plus a muted MP4 — sampled at custom offsets.

{
  "thumbnails": [
    {
      "mode": "animated",
      "width": 320,
      "duration_seconds": 4,
      "fps": 12,
      "start_offsets": [3.0, 7.5, 12.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.

• Transcodes the source into a single HLS output with a three-rung ABR ladder (1080p, 720p, 480p).
• Captures a 1280×720 JPEG poster frame at the 5-second mark.
• Builds a 320×180 JPEG sprite sheet every 10 seconds for scrubbing previews.

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

#Thumbnail results

Generated thumbnails are surfaced on the Job response in the thumbnail_results array, populated once the job completes. Each entry mirrors how output_url surfaces rendition results — the worker builds the storage key and URL, and the API echoes them verbatim.

A single spec can yield several results: interval and timestamps modes produce one entry per frame, sprite mode produces the sprite sheet image plus a .vtt sidecar (reported with format: "vtt"), and animated mode produces the animated WebP (format: "webp") plus the muted MP4 loop (format: "mp4"). Correlate each result back to the spec that produced it via mode + index.

For a worked thumbnail_results payload, see the Job object response.

#Validation rules

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