#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

#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.

• 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, and sprite mode produces the sprite sheet image plus a .vtt sidecar (reported with format: "vtt"). 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: