YouTube Thumbnail Downloader

YouTube Thumbnail Downloader

Download YouTube video thumbnails in bulk at your chosen resolution. Supports all URL formats, automatic quality fallback, and key-value store image saving.

Paste any YouTube URLs — watch pages, shorts, embeds — and get high-res thumbnails downloaded in seconds with zero browser overhead.

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 does YouTube Thumbnail Downloader do?

This actor downloads thumbnail images from YouTube videos in bulk. Paste any number of YouTube URLs (watch pages, Shorts, embeds, youtu.be links) and choose the resolution you want. The actor fetches each thumbnail from YouTube's CDN, optionally falls back to lower qualities when a resolution isn't available, and saves the images to the run's key-value store for direct download.

No browser is launched — the actor makes lightweight HTTP requests directly to img.youtube.com, making it fast and cheap to run.

Input parameters

Parameter	Type	Required	Default	Description
urls	array	Yes	—	List of YouTube video URLs (supports youtube.com/watch, youtu.be, /shorts/, /embed/, /v/)
thumbnailQuality	string	No	maxresdefault	Desired resolution: maxresdefault (1920×1080), sddefault (640×480), hqdefault (480×360), mqdefault (320×180)
enableFallback	boolean	No	true	If the requested quality isn't available, automatically try the next lower quality
saveToStore	boolean	No	true	Save each thumbnail image to the run's key-value store for direct download

Output example

{
    "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "videoId": "dQw4w9WgXcQ",
    "thumbnailQuality": "maxresdefault",
    "thumbnailUrl": "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "status": "ok"
}

Failed items include an error message:

{
    "url": "https://www.youtube.com/watch?v=INVALID",
    "videoId": null,
    "thumbnailQuality": null,
    "thumbnailUrl": null,
    "status": "failed",
    "error": "Invalid YouTube URL"
}

Use cases

• Content creation — Quickly grab thumbnails for video compilations, blog posts, or social media without manual screenshotting.
• Competitive analysis — Download competitor thumbnails in bulk to study design patterns, text overlays, and click-through strategies.
• Archiving — Preserve thumbnail images from playlists or channels before they change or videos get removed.
• Data labeling — Build image datasets for thumbnail quality classification, A/B testing analysis, or computer vision training.
• SEO monitoring — Track thumbnail changes over time by downloading them on a recurring schedule.

How it works

1. URL parsing — The actor accepts any standard YouTube URL format and extracts the 11-character video ID using regex.
2. Thumbnail download — For each video ID, the actor requests https://img.youtube.com/vi/{videoId}/{quality}.jpg from YouTube's CDN.
3. Placeholder detection — YouTube returns a tiny grey placeholder (~1 KB) instead of a 404 when a quality isn't available. The actor detects this by checking the response size.
4. Quality fallback — If the requested quality returns a placeholder and fallback is enabled, the actor walks down the chain: maxresdefault → sddefault → hqdefault → mqdefault → default.
5. Storage — When saveToStore is true, images are saved to the key-value store under the key {videoId}_{quality} with content type image/jpeg.
6. Dataset — A status row is pushed to the dataset for every URL, whether successful or failed.

Key-value store

When saveToStore is enabled (default), each downloaded thumbnail is saved to the run's key-value store. The key format is {videoId}_{quality}, for example dQw4w9WgXcQ_maxresdefault. You can access images via the Apify Console or the API:

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

Pricing

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

Each successfully downloaded thumbnail counts as one event. A run downloading 100 thumbnails costs $0.30 in actor charges plus Apify platform costs.

FAQ

What YouTube URL formats are supported? Standard watch URLs (youtube.com/watch?v=), short URLs (youtu.be/), Shorts (youtube.com/shorts/), embeds (youtube.com/embed/), and legacy /v/ links.

What happens if maxresdefault isn't available? With enableFallback turned on (default), the actor automatically tries sddefault, then hqdefault, then mqdefault. The actual quality used is recorded in the thumbnailQuality output field.

How does the actor detect unavailable qualities? YouTube returns a small grey placeholder image (~1 KB) instead of a 404. The actor checks the response size — real thumbnails are always larger than 1.5 KB.

Can I download thumbnails from private or age-restricted videos? No. YouTube's CDN only serves thumbnails for public videos. Private or deleted videos will return a failed status.

How fast is it? Very fast. Each thumbnail is a single HTTP GET — no browser is involved. A batch of 100 URLs typically completes in under 30 seconds.

Does it need a proxy? No. YouTube's thumbnail CDN (img.youtube.com) is publicly accessible and doesn't rate-limit moderate usage.

Legal and compliance

This actor downloads publicly available thumbnail images from YouTube's CDN (img.youtube.com). Thumbnails are public assets served without authentication. Users are responsible for ensuring their use of downloaded images complies with YouTube's Terms of Service and applicable copyright laws.