How to Get a YouTube Thumbnail URL From a Video ID

The quickest way to get a YouTube thumbnail URL is to place the video ID in YouTube’s image-host pattern:

https://i.ytimg.com/vi/VIDEO_ID/hqdefault.jpg

For example, the official YouTube API guide demonstrates:

https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg

Replace 7lCDEYXw3mM with your video’s ID. If your application must know which thumbnail sizes actually exist, call the YouTube Data API videos.list endpoint with part=snippet and use the URLs returned in snippet.thumbnails. Available variants differ between videos.

1. What is the YouTube thumbnail URL format?

The URL has three parts:

1. The image host: https://i.ytimg.com
2. The video path: /vi/VIDEO_ID/
3. A thumbnail filename such as default.jpg, mqdefault.jpg, or hqdefault.jpg

https://i.ytimg.com/vi/VIDEO_ID/default.jpg
https://i.ytimg.com/vi/VIDEO_ID/mqdefault.jpg
https://i.ytimg.com/vi/VIDEO_ID/hqdefault.jpg

The official getting-started guide shows these direct image URLs in a videos.list response, including the hqdefault.jpg form. Treat manual construction as a convenient lookup pattern, then verify the response for the particular video when availability matters. Google’s YouTube Data API getting-started guide

2. Find the video ID before building the URL

Use only the ID, not the complete YouTube URL.

Input URL	Video ID
https://www.youtube.com/watch?v=7lCDEYXw3mM	7lCDEYXw3mM
https://youtu.be/7lCDEYXw3mM	7lCDEYXw3mM
https://www.youtube.com/watch?v=7lCDEYXw3mM&t=30s	7lCDEYXw3mM

For a standard watch URL, take the value after v= and stop at the next &. For a shortened youtu.be URL, take the path segment and discard any query string. Do not pass a playlist ID, channel ID, timestamp, or the full URL into the /vi/ path.

JavaScript ID extraction

function getYouTubeVideoId(value) {
  const url = new URL(value);

  if (url.hostname === 'youtu.be') {
    return url.pathname.slice(1).split('/')[0];
  }

  if (url.hostname.endsWith('youtube.com')) {
    if (url.pathname === '/watch') return url.searchParams.get('v');
    if (url.pathname.startsWith('/shorts/')) return url.pathname.split('/')[2];
    if (url.pathname.startsWith('/embed/')) return url.pathname.split('/')[2];
  }

  return null;
}

const id = getYouTubeVideoId('https://www.youtube.com/watch?v=7lCDEYXw3mM&t=30s');
if (!id) throw new Error('No YouTube video ID found');
const thumbnailUrl = `https://i.ytimg.com/vi/${id}/hqdefault.jpg`;
console.log(thumbnailUrl);

3. Choose a thumbnail size

YouTube documents these typical dimensions for video thumbnail variants:

Variant	Typical dimensions	Use
default	120×90	Small lists and compact previews
mqdefault	320×180	Medium cards
hqdefault	480×360	General-purpose previews
sddefault	640×480	Standard larger images
maxresdefault	1280×720	Highest commonly documented video thumbnail

These are typical sizes, not a promise that every file exists for every video. Standard and max-resolution thumbnails are available only for some videos, and the available dimensions can depend on the source video’s resolution. The videos resource documentation and thumbnail resource documentation describe the variants and availability rules.

How do I get the max-resolution thumbnail?

Try:

https://i.ytimg.com/vi/VIDEO_ID/maxresdefault.jpg

If it returns a missing image or a fallback, request the video’s metadata and select the largest URL that YouTube actually returns. Do not assume that maxresdefault.jpg exists.

4. Retrieve an available URL with YouTube Data API

For production software, call videos.list with the video ID and part=snippet. The response contains a snippet.thumbnails map. Each returned entry can include a url, width, and height. Select a named variant when present, or choose the entry with the greatest area.

Endpoint:

GET https://www.googleapis.com/youtube/v3/videos
  ?part=snippet
  &id=VIDEO_ID
  &key=YOUR_API_KEY

The API response can contain default, medium, high, standard, and maxres. A missing item means that variant was not returned for that video.

cURL

curl --get 'https://www.googleapis.com/youtube/v3/videos' \
  --data-urlencode 'part=snippet' \
  --data-urlencode 'id=7lCDEYXw3mM' \
  --data-urlencode 'key=YOUR_API_KEY'

Python

import requests

video_id = "7lCDEYXw3mM"
r = requests.get(
    "https://www.googleapis.com/youtube/v3/videos",
    params={"part": "snippet", "id": video_id, "key": "YOUR_API_KEY"},
    timeout=30,
)
r.raise_for_status()
data = r.json()

items = data.get("items", [])
if not items:
    raise ValueError("Video not found or not available to this API request")

thumbnails = items[0]["snippet"].get("thumbnails", {})
preferred = ["maxres", "standard", "high", "medium", "default"]
for name in preferred:
    if name in thumbnails and thumbnails[name].get("url"):
        print(thumbnails[name]["url"])
        break
else:
    raise ValueError("No thumbnail URL returned")

Node.js

const videoId = '7lCDEYXw3mM';
const params = new URLSearchParams({
  part: 'snippet',
  id: videoId,
  key: 'YOUR_API_KEY'
});

const res = await fetch(`https://www.googleapis.com/youtube/v3/videos?${params}`);
if (!res.ok) throw new Error(`YouTube API returned ${res.status}`);
const data = await res.json();
const item = data.items?.[0];
if (!item) throw new Error('Video not found or unavailable');

const thumbnails = item.snippet?.thumbnails ?? {};
const preferred = ['maxres', 'standard', 'high', 'medium', 'default'];
const selected = preferred.map(name => thumbnails[name]).find(Boolean);
if (!selected?.url) throw new Error('No thumbnail URL returned');
console.log(selected.url);

5. Search results versus a video-specific lookup

Search responses include thumbnail metadata, but the search documentation says fhd, qhd, and uhd are not supported for search results. If you need higher-resolution metadata for one known video, use the resource-specific videos.list request instead. YouTube search documentation

Do not use thumbnails.set to retrieve an existing thumbnail. That method uploads and associates a new custom thumbnail with a video. thumbnails.set documentation

6. Troubleshooting common errors

Symptom	Likely cause	Fix
404 or a missing image for maxresdefault.jpg	The video does not have that variant.	Call videos.list and fall back to standard, high, or another returned entry.
The URL shows a generic or unexpected image	The ID is wrong, truncated, or includes query parameters.	Extract only the video ID and compare it with the watch URL.
items is empty	The ID is invalid, the video is unavailable, or the API request cannot access it.	Check the ID, privacy status, region restrictions, API key, and enabled YouTube Data API.
HTTP 400 from the API	A required parameter is missing or malformed.	Send part=snippet, a valid id, and a valid API key.
HTTP 403 from the API	The key is invalid, restricted incorrectly, or quota is exhausted.	Review API-key restrictions and quota in Google Cloud, then retry with a permitted key.
Search result has no desired high-resolution field	Some high-resolution fields are unsupported in search results.	Use videos.list for the known video ID.

7. Reliability, performance, and caching

• For one-off links, direct URL construction is fastest because it avoids an API request.
• For many videos or user-submitted URLs, resolve IDs once, store the API-returned URL and dimensions, and refresh only when needed.
• Cache by video ID and variant. A failed maxres lookup should not be retried on every page request; record the fallback that succeeded.
• Use the width and height fields when choosing an image for a fixed layout. They let you avoid requesting a large image for a small card.
• Keep your YouTube API key on the server. Do not expose it in browser JavaScript.
• Handle missing videos and missing variants as normal states. Your UI should have a placeholder or a lower-resolution fallback.

8. Or skip the browser setup with ScreenshotNeo

If you need a rendered image of a thumbnail URL for a social card, documentation page, visual test, or archive, ScreenshotNeo can capture the resolved image URL through one GET request. It is a screenshot API and MCP server; it does not replace YouTube’s API for discovering which thumbnail variants exist.

After you obtain the URL from the direct pattern or videos.list, pass it to ScreenshotNeo. See the ScreenshotNeo API documentation for all options.

cURL

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg -o thumbnail.webp

Python

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg"}, timeout=90)
r.raise_for_status()
open("thumbnail.webp", "wb").write(r.content)

Node.js

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://i.ytimg.com/vi/7lCDEYXw3mM/hqdefault.jpg' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
const buffer = Buffer.from(await res.arrayBuffer());
require('node:fs').writeFileSync('thumbnail.webp', buffer);

ScreenshotNeo removes cookie and consent banners, newsletter popups, and chat widgets before capture; bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, with the result identified by X-Page-Verdict and X-Billed headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 screenshots per month with no card, and paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

9. Frequently asked questions

Can I get a thumbnail URL without an API key?

Yes. Manual construction with https://i.ytimg.com/vi/VIDEO_ID/hqdefault.jpg needs no YouTube Data API key. Use the API when you need availability and dimensions for a particular video.

Is maxresdefault.jpg always 1280×720?

1280×720 is the typical documented size. The variant can be unavailable, so check the API response before relying on it.

Can I use a thumbnail URL in an HTML image tag?

Yes. Use the URL returned by YouTube or a verified constructed URL as the src value, and provide an appropriate alt attribute.

How do I get a custom thumbnail uploaded by a channel owner?

The thumbnail URL is still exposed through the video’s thumbnail metadata when available. The thumbnails.set endpoint is for uploading a replacement, not retrieving one.