YouTube Thumbnail Downloader

YouTube Thumbnail Downloader

Download YouTube video thumbnails in bulk from watch pages, Shorts, embeds, live URLs, and youtu.be links. Choose the thumbnail resolution, use automatic quality fallback, and save full-size JPG images to the Apify key-value store for direct download.

Paste YouTube URLs and get high-resolution thumbnails in seconds with no browser, no YouTube API key, and no manual screenshot workflow.

Copy to your AI assistant

Copy this block into ChatGPT, Claude, Cursor, or any LLM to start using this Actor.

Apify Actor: parsebird/youtube-thumbnail-downloader. Downloads YouTube video thumbnails in bulk. Call via ApifyClient: client.actor("parsebird/youtube-thumbnail-downloader").call(run_input={"urls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "thumbnailQuality": "maxresdefault", "enableFallback": true, "saveToStore": true}). Returns per-video status: videoId, thumbnailQuality, thumbnailUrl, status. Images saved to KV store as {videoId}_{quality}. Full API spec: https://apify.com/parsebird/youtube-thumbnail-downloader/api. Get your token: https://console.apify.com/settings/integrations.

What is YouTube Thumbnail Downloader?

YouTube Thumbnail Downloader is an Apify Actor that downloads thumbnail images from YouTube videos in bulk. It extracts the video ID from common YouTube URL formats, requests the selected image quality from YouTube's thumbnail CDN, and returns structured metadata for every URL.

Use it as a lightweight YouTube thumbnail API alternative when you need saved JPG files, repeatable batch runs, API access, scheduling, and exportable results without building your own downloader.

What can YouTube Thumbnail Downloader do?

• Download YouTube thumbnails from many URLs in one run.
• Support watch pages, Shorts, embeds, live URLs, legacy /v/ URLs, and youtu.be short links.
• Choose maxresdefault, sddefault, hqdefault, or mqdefault image quality.
• Detect YouTube placeholder images when a requested quality is unavailable.
• Fall back through lower resolutions automatically when maxresdefault does not exist.
• Save thumbnail JPG files to the run's key-value store for direct download.
• Return a clean dataset with the source URL, video ID, final thumbnail URL, quality, status, and error message.
• Run without a browser or proxy for fast, low-cost thumbnail extraction.
• Use Apify API, schedules, webhooks, integrations, and exports to automate thumbnail monitoring.

Why download YouTube thumbnails?

YouTube thumbnails are useful for content workflows, competitor analysis, creative research, archives, and machine learning datasets. With YouTube Thumbnail Downloader, you can scrape YouTube thumbnail images at scale and keep a record of which resolution was actually available for each video.

Common use cases include:

• Content creation - Grab thumbnails for blog posts, creator research, video roundups, or social media planning.
• Competitive analysis - Download competitor thumbnails in bulk to study layout, text overlays, faces, colors, and click-through patterns.
• Thumbnail archiving - Preserve YouTube thumbnail images before videos are removed or thumbnails are changed.
• SEO monitoring - Schedule recurring runs and compare thumbnail changes over time.
• Data labeling - Build image datasets for thumbnail quality checks, A/B testing, or computer vision training.

What data can you extract from YouTube?

Field	Description
url	Original YouTube URL from your input.
videoId	Extracted 11-character YouTube video ID.
thumbnailQuality	Final quality that was downloaded, such as maxresdefault or hqdefault.
thumbnailUrl	Direct image URL on img.youtube.com.
status	ok for successful downloads or failed for invalid/unavailable thumbnails.
error	Error message for failed items, such as invalid URL or unavailable thumbnail.

Downloaded image files are saved separately in the key-value store when saveToStore is enabled.

How to use YouTube Thumbnail Downloader

1. Open YouTube Thumbnail Downloader on Apify.
2. Click Try for free or open the Input tab.
3. Paste one or more YouTube video URLs into YouTube URLs.
4. Choose the thumbnail quality you want: maxresdefault, sddefault, hqdefault, or mqdefault.
5. Keep Enable Quality Fallback turned on if you want the Actor to try lower resolutions automatically.
6. Keep Save Images to Key-Value Store turned on if you want downloadable JPG files.
7. Run the Actor and open the dataset for metadata or the key-value store for image files.
8. Download results in JSON, CSV, Excel, XML, RSS, or HTML from the Apify Console.

Example YouTube URL you can use for a quick test:

How much does it cost to download YouTube thumbnails?

YouTube Thumbnail Downloader uses pay-per-event pricing.

Event	Price per event	Price per 1,000 downloaded thumbnails
thumbnail-downloaded	$0.003	$3.00

Each successfully downloaded thumbnail counts as one charged event. Failed URLs, invalid URLs, and unavailable thumbnails are returned in the dataset but do not trigger the thumbnail-downloaded event in the current Actor implementation.

Example: downloading 100 available thumbnails costs $0.30 in Actor charges, plus any standard Apify platform usage costs.

Input / Output

Input parameters

Parameter	Type	Required	Default	Description
urls	array	Yes	-	List of YouTube video URLs. Supports youtube.com/watch, youtu.be, Shorts, embeds, live URLs, and /v/ links.
thumbnailQuality	string	No	maxresdefault	Desired resolution: maxresdefault (1920x1080), sddefault (640x480), hqdefault (480x360), or mqdefault (320x180).
enableFallback	boolean	No	true	If the requested quality is unavailable, try the next lower quality automatically.
saveToStore	boolean	No	true	Save each downloaded JPG image to the run's key-value store.

Example input

{
  "urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/9bZkp7q19f0",
    "https://www.youtube.com/shorts/gJPFnmr0ML0"
  ],
  "thumbnailQuality": "maxresdefault",
  "enableFallback": true,
  "saveToStore": true
}

Example output

[
  {
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "videoId": "dQw4w9WgXcQ",
    "thumbnailQuality": "maxresdefault",
    "thumbnailUrl": "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "status": "ok"
  },
  {
    "url": "https://www.youtube.com/watch?v=INVALID",
    "videoId": null,
    "thumbnailQuality": null,
    "thumbnailUrl": null,
    "status": "failed",
    "error": "Invalid YouTube URL"
  }
]

Download the dataset in JSON, HTML, CSV, Excel, XML, or RSS. When saveToStore is enabled, image records are saved to the key-value store with this key format:

{videoId}_{quality}

For example:

dQw4w9WgXcQ_maxresdefault

You can access a stored thumbnail through the Apify API:

https://api.apify.com/v2/key-value-stores/{storeId}/records/{videoId}_{quality}

How does YouTube Thumbnail Downloader work?

1. The Actor reads your list of YouTube URLs.
2. It extracts the 11-character YouTube video ID from each URL.
3. It requests https://img.youtube.com/vi/{videoId}/{quality}.jpg.
4. It checks the response size to detect YouTube's small placeholder image for unavailable qualities.
5. If fallback is enabled, it tries lower qualities in this order: maxresdefault, sddefault, hqdefault, mqdefault, default.
6. It saves successful JPG files to the key-value store if enabled.
7. It pushes one dataset item per processed URL with success or failure status.

Is it legal to scrape YouTube thumbnails?

YouTube Thumbnail Downloader downloads publicly accessible thumbnail images from YouTube's thumbnail CDN, img.youtube.com. The Actor does not bypass login, private video access, paywalls, or technical protections.

You are responsible for using downloaded images in a way that complies with YouTube's Terms of Service, copyright law, and any applicable rules in your jurisdiction. For general guidance, read Apify's overview: Is web scraping legal?

Other YouTube scrapers and related Actors

These Actors can pair well with YouTube Thumbnail Downloader in content, media, and data workflows:

Actor	Use it for
YouTube Search Scraper & API	Scrape YouTube search results.
Unsplash Image Scraper	Collect image metadata and visual inspiration from Unsplash.
HTTP Request Actor	Fetch URLs, APIs, and files as part of custom automation workflows.

FAQ

What YouTube URL formats are supported?

YouTube Thumbnail Downloader supports standard watch URLs (youtube.com/watch?v=), short links (youtu.be/), Shorts (youtube.com/shorts/), embeds (youtube.com/embed/), live URLs (youtube.com/live/), and legacy /v/ links.

Can I download YouTube Shorts thumbnails?

Yes. Paste a YouTube Shorts URL and the Actor extracts the video ID the same way it does for regular videos.

What happens if maxresdefault is not available?

With enableFallback turned on, the Actor automatically tries sddefault, then hqdefault, then mqdefault, then default. The actual downloaded quality is shown in the thumbnailQuality output field.

Why do some videos not have a max-resolution thumbnail?

Not every YouTube video has a maxresdefault thumbnail. YouTube may only expose lower-resolution thumbnail files, especially for older videos, Shorts, or videos uploaded without a custom high-resolution thumbnail.

Can I download thumbnails from private or deleted videos?

No. YouTube's CDN only serves thumbnails that are publicly available. Private, removed, or unavailable videos may return a failed status.

Does this Actor use the YouTube API?

No. YouTube Thumbnail Downloader requests public thumbnail image URLs directly from img.youtube.com. You do not need a YouTube API key.

Can I use this as a YouTube thumbnail API?

Yes. You can run the Actor through the Apify API, the API tab, Apify Client for Python or JavaScript, schedules, and webhooks.

How fast is it?

The Actor is usually fast because every thumbnail is a direct HTTP GET request and no browser is launched. Batch speed depends on the number of URLs and network conditions.

Does it need a proxy?

No proxy is required for normal use. The Actor downloads publicly available thumbnail images from YouTube's CDN.

Where are the image files stored?

When saveToStore is enabled, each JPG thumbnail is saved to the run's default key-value store. The dataset stores metadata and direct thumbnail URLs; the key-value store stores the actual image files.

How can I report an issue or request a feature?

Open the Issues tab on the Actor page and share the input URL, expected behavior, and run ID if possible. Feature requests for new URL formats, extra output fields, or workflow integrations are welcome.