thumbnailUrl

thumbnailUrl · Required

Appears in

VideoObject

What is it?

thumbnailUrl is the URL of the preview image that represents a video. Search engines display this thumbnail in video rich results, Google Discover, and the Video tab. Without it, Google will not generate a video rich result for the page.

Why this matters for AEO

When a user asks an AI assistant "how to replace a bike chain" and a video answers that query, the AI engine pulls thumbnailUrl to show a visual preview alongside the video title and description. A missing or broken thumbnail means the video cannot be surfaced in visual answer panels or video carousels. AI engines that render rich cards treat this field as a hard requirement for video content.

What the specs say

Schema.org: URL. A thumbnail image relevant to the Thing. schema.org/thumbnailUrl

Google: Required. "A URL pointing to the video's unique thumbnail image file. Follow the thumbnail image guidelines." Google Video Structured Data

Google specifies thumbnail image guidelines that require images to be at least 120x120 pixels.

How to find your value

• YouTube — Right click video > Copy thumbnail URL, or use https://img.youtube.com/vi/VIDEO_ID/maxresdefault.jpg
• Vimeo — Vimeo API returns thumbnail_url in oEmbed response
• Self-hosted — The poster image you set in the <video> tag's poster attribute
• Wistia — Wistia dashboard > Video > Thumbnail, or API thumbnail.url
• CMS — The featured image or video thumbnail field in your CMS

Format and code

Expected type: URL (string)

Accepts a single URL string or an array of URLs. Google reads the first URL if an array is provided.

{
  "@context": "https://schema.org",
  "@type": "VideoObject",
  "name": "How to Replace a Bike Chain",
  "thumbnailUrl": "https://example.com/images/bike-chain-thumb.jpg",
  "uploadDate": "2024-03-15T10:00:00Z",
  "description": "Step-by-step guide to replacing a bicycle chain"
}

Array format (also valid):

{
  "thumbnailUrl": [
    "https://example.com/images/video-thumb-1200.jpg",
    "https://example.com/images/video-thumb-600.jpg"
  ]
}

Invalid: A page URL instead of an image file URL. The thumbnail must be a direct link to an image file, not the page containing the video.

Webflow implementation

Static pages

In Page Settings > Custom Code > Head Code, add the full VideoObject JSON-LD block with the thumbnailUrl hardcoded to your video's poster image URL.

CMS template pages

Use a CMS Image field for the video thumbnail. Reference it in your JSON-LD embed:

"thumbnailUrl": "{{wf {"path":"video-thumbnail","type":"ImageRef"} }}"

Make sure the CMS field outputs a full URL, not a relative path.

In Schema HQ

Field mapping pulls CMS image field to thumbnailUrl automatically when generating VideoObject markup. It validates the URL resolves to an actual image and flags broken thumbnails before publishing.

Real examples

Hotstar uses an array format for thumbnailUrl:

{
  "@type": "VideoObject",
  "name": "Action Recap: Pakistan vs India",
  "thumbnailUrl": [
    "https://img1.hotstarext.com/image/upload/f_auto,t_hcdl/sources/r1/cms/prod/9889/1589889-h-655968c7423d"
  ]
}

Source: hotstar.com

TED Talks uses a single URL string:

{
  "@type": "VideoObject",
  "name": "The levitating superconductor",
  "thumbnailUrl": "https://tedcdnpi-a.akamaihd.net/r/tedcdnpe-a.akamaihd.net/images/ted/b9693798223a4101be834398af15df5560d3f25c_1600x1200.jpg"
}

Source: ted.com

Related fields

• name · The video title displayed in search results
• description · Text summary shown alongside the thumbnail
• uploadDate · When the video was first published
• embedUrl · URL of the video player
• contentUrl · Direct link to the video file

FAQ

Can thumbnailUrl be an array?

Yes. Both a single URL string and an array of URLs are valid. Google reads the first URL in the array. Hotstar uses the array format in production.

What size should the thumbnail be?

Google requires a minimum of 120x120 pixels. Larger images perform better in search results. Use the highest resolution thumbnail your video host provides.

Does the thumbnail have to be unique per video?

Google specifies "the video's unique thumbnail image file." Using the same generic placeholder thumbnail across multiple videos reduces the chance of earning video rich results for any of them.