# YouTube Thumbnail Downloader (`parsebird/youtube-thumbnail-downloader`) Actor
Download YouTube video thumbnails in bulk. Choose quality, auto-fallback to lower resolutions, and save images to key-value store or dataset.
- **URL**: https://apify.com/parsebird/youtube-thumbnail-downloader.md
- **Developed by:** [ParseBird](https://apify.com/parsebird) (community)
- **Categories:** Videos, Automation, SEO tools
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 1 bookmarks
- **User rating**: No ratings yet
## Pricing
from $3.00 / 1,000 thumbnail downloadeds
This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event
## What's an Apify Actor?
Actors are a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".
## How to integrate an Actor?
If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.
In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md):
```bash
npm install apify-client
```
In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md):
```bash
pip install apify-client
```
In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md):
````bash
# MacOS / Linux
curl -fsSL https://apify.com/install-cli.sh | bash
# Windows
irm https://apify.com/install-cli.ps1 | iex
```bash
In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md).
If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md).
For usage examples, see the [API](#api) section below.
For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).
# README
### 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
```json
{
"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:
```json
{
"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.
# Actor input Schema
## `urls` (type: `array`):
List of YouTube video URLs (supports youtube.com/watch, youtu.be, shorts, embeds).
## `thumbnailQuality` (type: `string`):
Desired thumbnail resolution. maxresdefault is 1920x1080, sddefault is 640x480, hqdefault is 480x360, mqdefault is 320x180.
## `enableFallback` (type: `boolean`):
If the requested quality is unavailable, automatically try the next lower quality.
## `saveToStore` (type: `boolean`):
Save each thumbnail image to the run's key-value store for direct download.
## Actor input object example
```json
{
"urls": [
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://youtu.be/9bZkp7q19f0"
],
"thumbnailQuality": "maxresdefault",
"enableFallback": true,
"saveToStore": true
}
```
# Actor output Schema
## `dataset` (type: `string`):
No description
# API
You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.
## JavaScript example
```javascript
import { ApifyClient } from 'apify-client';
// Initialize the ApifyClient with your Apify API token
// Replace the '' with your token
const client = new ApifyClient({
token: '',
});
// Prepare Actor input
const input = {
"urls": [
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://youtu.be/9bZkp7q19f0"
],
"thumbnailQuality": "maxresdefault"
};
// Run the Actor and wait for it to finish
const run = await client.actor("parsebird/youtube-thumbnail-downloader").call(input);
// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
console.dir(item);
});
// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs
```
## Python example
```python
from apify_client import ApifyClient
# Initialize the ApifyClient with your Apify API token
# Replace '' with your token.
client = ApifyClient("")
# Prepare the Actor input
run_input = {
"urls": [
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://youtu.be/9bZkp7q19f0",
],
"thumbnailQuality": "maxresdefault",
}
# Run the Actor and wait for it to finish
run = client.actor("parsebird/youtube-thumbnail-downloader").call(run_input=run_input)
# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
print(item)
# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start
```
## CLI example
```bash
echo '{
"urls": [
"https://www.youtube.com/watch?v=dQw4w9WgXcQ",
"https://youtu.be/9bZkp7q19f0"
],
"thumbnailQuality": "maxresdefault"
}' |
apify call parsebird/youtube-thumbnail-downloader --silent --output-dataset
```
## MCP server setup
```json
{
"mcpServers": {
"apify": {
"command": "npx",
"args": [
"mcp-remote",
"https://mcp.apify.com/?tools=parsebird/youtube-thumbnail-downloader",
"--header",
"Authorization: Bearer "
]
}
}
}
```
## OpenAPI specification
```json
{
"openapi": "3.0.1",
"info": {
"title": "YouTube Thumbnail Downloader",
"description": "Download YouTube video thumbnails in bulk. Choose quality, auto-fallback to lower resolutions, and save images to key-value store or dataset.",
"version": "1.0",
"x-build-id": "ZcafqnwpeyyONbgTR"
},
"servers": [
{
"url": "https://api.apify.com/v2"
}
],
"paths": {
"/acts/parsebird~youtube-thumbnail-downloader/run-sync-get-dataset-items": {
"post": {
"operationId": "run-sync-get-dataset-items-parsebird-youtube-thumbnail-downloader",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
},
"/acts/parsebird~youtube-thumbnail-downloader/runs": {
"post": {
"operationId": "runs-sync-parsebird-youtube-thumbnail-downloader",
"x-openai-isConsequential": false,
"summary": "Executes an Actor and returns information about the initiated run in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/runsResponseSchema"
}
}
}
}
}
}
},
"/acts/parsebird~youtube-thumbnail-downloader/run-sync": {
"post": {
"operationId": "run-sync-parsebird-youtube-thumbnail-downloader",
"x-openai-isConsequential": false,
"summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
"tags": [
"Run Actor"
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/inputSchema"
}
}
}
},
"parameters": [
{
"name": "token",
"in": "query",
"required": true,
"schema": {
"type": "string"
},
"description": "Enter your Apify token here"
}
],
"responses": {
"200": {
"description": "OK"
}
}
}
}
},
"components": {
"schemas": {
"inputSchema": {
"type": "object",
"required": [
"urls"
],
"properties": {
"urls": {
"title": "YouTube URLs",
"type": "array",
"description": "List of YouTube video URLs (supports youtube.com/watch, youtu.be, shorts, embeds).",
"items": {
"type": "string"
}
},
"thumbnailQuality": {
"title": "Thumbnail Quality",
"enum": [
"maxresdefault",
"sddefault",
"hqdefault",
"mqdefault"
],
"type": "string",
"description": "Desired thumbnail resolution. maxresdefault is 1920x1080, sddefault is 640x480, hqdefault is 480x360, mqdefault is 320x180.",
"default": "maxresdefault"
},
"enableFallback": {
"title": "Enable Quality Fallback",
"type": "boolean",
"description": "If the requested quality is unavailable, automatically try the next lower quality.",
"default": true
},
"saveToStore": {
"title": "Save Images to Key-Value Store",
"type": "boolean",
"description": "Save each thumbnail image to the run's key-value store for direct download.",
"default": true
}
}
},
"runsResponseSchema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"actId": {
"type": "string"
},
"userId": {
"type": "string"
},
"startedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"finishedAt": {
"type": "string",
"format": "date-time",
"example": "2025-01-08T00:00:00.000Z"
},
"status": {
"type": "string",
"example": "READY"
},
"meta": {
"type": "object",
"properties": {
"origin": {
"type": "string",
"example": "API"
},
"userAgent": {
"type": "string"
}
}
},
"stats": {
"type": "object",
"properties": {
"inputBodyLen": {
"type": "integer",
"example": 2000
},
"rebootCount": {
"type": "integer",
"example": 0
},
"restartCount": {
"type": "integer",
"example": 0
},
"resurrectCount": {
"type": "integer",
"example": 0
},
"computeUnits": {
"type": "integer",
"example": 0
}
}
},
"options": {
"type": "object",
"properties": {
"build": {
"type": "string",
"example": "latest"
},
"timeoutSecs": {
"type": "integer",
"example": 300
},
"memoryMbytes": {
"type": "integer",
"example": 1024
},
"diskMbytes": {
"type": "integer",
"example": 2048
}
}
},
"buildId": {
"type": "string"
},
"defaultKeyValueStoreId": {
"type": "string"
},
"defaultDatasetId": {
"type": "string"
},
"defaultRequestQueueId": {
"type": "string"
},
"buildNumber": {
"type": "string",
"example": "1.0.0"
},
"containerUrl": {
"type": "string"
},
"usage": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "integer",
"example": 1
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
},
"usageTotalUsd": {
"type": "number",
"example": 0.00005
},
"usageUsd": {
"type": "object",
"properties": {
"ACTOR_COMPUTE_UNITS": {
"type": "integer",
"example": 0
},
"DATASET_READS": {
"type": "integer",
"example": 0
},
"DATASET_WRITES": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_READS": {
"type": "integer",
"example": 0
},
"KEY_VALUE_STORE_WRITES": {
"type": "number",
"example": 0.00005
},
"KEY_VALUE_STORE_LISTS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_READS": {
"type": "integer",
"example": 0
},
"REQUEST_QUEUE_WRITES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_INTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"DATA_TRANSFER_EXTERNAL_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
"type": "integer",
"example": 0
},
"PROXY_SERPS": {
"type": "integer",
"example": 0
}
}
}
}
}
}
}
}
}
}
```