YouTube Thumbnail Downloader

Download high-resolution YouTube video thumbnails in HD (1080p/720p maxresdefault), Standard Definition (sddefault), High Quality (hqdefault), and more.

Supports all YouTube URL formats (standard watch URLs, YouTube Shorts, embeds, shortened youtu.be links, and raw 11-character video IDs). Download images directly into the Apify Key-Value Store or extract direct image CDN URLs and metadata to your dataset.

---

✨ Features

• Highest Available Quality (HD): Automatically fetches the maximum resolution thumbnail (maxresdefault, 1280x720) whenever available.
• Intelligent Quality Cascade: If maximum resolution is not available for older or lower-resolution videos, it automatically cascades to the next best available quality (sddefault -> hqdefault -> mqdefault -> default).
• All URL Formats Supported:
  • https://www.youtube.com/watch?v=VIDEO_ID
  • https://youtu.be/VIDEO_ID
  • https://www.youtube.com/shorts/VIDEO_ID
  • https://www.youtube.com/embed/VIDEO_ID
  • https://www.youtube.com/live/VIDEO_ID
  • Direct 11-character video IDs: VIDEO_ID
• Key-Value Store Image Storage: Save JPEG thumbnail files directly to the Apify Key-Value Store for one-click browser preview and download.
• Comprehensive Resolution Links: Generates direct links for all standard YouTube thumbnail resolutions in each dataset record.
• Batch Processing: Process dozens or hundreds of video URLs in a single run.

---

📥 Input

The Actor accepts the following input parameters:

Field	Type	Description	Default
urls	Array of strings	List of YouTube video URLs, shorts URLs, or 11-character video IDs.	["https://www.youtube.com/watch?v=dQw4w9WgXcQ"]
preferredQuality	String (select)	Preferred thumbnail quality: maxresdefault, sddefault, hqdefault, mqdefault, or default.	"maxresdefault"
downloadToStore	Boolean	Whether to download the thumbnail image into the Key-Value Store.	true

Input Example

{
  "urls": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
    "https://youtu.be/jNQXAC9IVRw",
    "https://www.youtube.com/shorts/kJQP7kiw5Fk"
  ],
  "preferredQuality": "maxresdefault",
  "downloadToStore": true
}

---

📤 Output

Each processed video is stored as a record in the default Apify Dataset.

Dataset Output Example

{
  "videoId": "dQw4w9WgXcQ",
  "inputUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "success": true,
  "quality": "maxresdefault",
  "width": 1280,
  "height": 720,
  "thumbnailUrl": "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "fileSizeBytes": 65324,
  "keyValueStoreKey": "THUMBNAIL_dQw4w9WgXcQ.jpg",
  "keyValueStoreUrl": "https://api.apify.com/v2/key-value-stores/<STORE_ID>/records/THUMBNAIL_dQw4w9WgXcQ.jpg",
  "allThumbnails": {
    "maxresdefault": "https://img.youtube.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
    "sddefault": "https://img.youtube.com/vi/dQw4w9WgXcQ/sddefault.jpg",
    "hqdefault": "https://img.youtube.com/vi/dQw4w9WgXcQ/hqdefault.jpg",
    "mqdefault": "https://img.youtube.com/vi/dQw4w9WgXcQ/mqdefault.jpg",
    "default": "https://img.youtube.com/vi/dQw4w9WgXcQ/default.jpg"
  },
  "error": null
}

Key-Value Store

When downloadToStore is true, each thumbnail image is saved as THUMBNAIL_<videoId>.jpg in your default Key-Value Store with image/jpeg content type. You can preview and download the JPEG images directly in the Apify Console under the Storage -> Key-value store tab.

---

📐 Thumbnail Quality Levels

Quality Code	Resolution	Aspect Ratio	Availability
maxresdefault	1280 × 720	16:9	HD/4K videos (falls back if unavailable)
sddefault	640 × 480	4:3	Standard Definition videos
hqdefault	480 × 360	4:3	Available for virtually all videos
mqdefault	320 × 180	16:9	Medium quality
default	120 × 90	4:3	Smallest thumbnail placeholder

---

💡 Use Cases

• Content Creation & Marketing: Analyze competitor thumbnails, designs, colors, and typography.
• Dataset Collection: Gather training data for computer vision or image classification models.
• Video Archiving & Catalogs: Back up artwork and thumbnails for media management systems.
• Social Media Management: Automatically fetch high-res cover art for cross-platform sharing.