# YouTube Thumbnail Downloader (`maximedupre/youtube-thumbnails`) Actor

Get direct public YouTube thumbnail links from a list of video URLs or IDs. Choose the requested quality, see pixel dimensions, and optionally include video context or other available quality links. Unavailable items are reported while the run continues.

- **URL**: https://apify.com/maximedupre/youtube-thumbnails.md
- **Developed by:** [Maxime Dupré](https://apify.com/maximedupre) (community)
- **Categories:** Social media, Developer tools, Automation
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

$2.70 / 1,000 thumbnails

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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
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.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — 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

### 🖼️ Get public YouTube thumbnails from known links

YouTube Thumbnails is for creators, content researchers, and developers who already have public YouTube video references. Add a list of video links or bare video IDs and get a dataset row for each successful thumbnail retrieval. Each row includes the source reference, video ID, requested and delivered quality, a direct thumbnail URL, and pixel dimensions. You can also add public video context or links for other available qualities.

Use it to collect thumbnails for content reviews, creative research, video audits, and other workflows that need source-backed image links.

**Try these workflows**

- Find a direct image link for a public video with **[YouTube Thumbnail URL](https://apify.com/maximedupre/youtube-thumbnails/examples/youtube-thumbnail-url)**.
- Check a Shorts thumbnail's pixel dimensions with **[YouTube Shorts Thumbnail Size](https://apify.com/maximedupre/youtube-thumbnails/examples/youtube-shorts-thumbnail-size)**.
- Get a thumbnail download link from a public video with **[YouTube Thumbnail Download](https://apify.com/maximedupre/youtube-thumbnails/examples/youtube-thumbnail-download)**.
- Look up one public video thumbnail with **[YouTube Thumbnail](https://apify.com/maximedupre/youtube-thumbnails/examples/youtube-thumbnail)**.
- Read the width and height of a selected thumbnail with **[YouTube Thumbnail Size](https://apify.com/maximedupre/youtube-thumbnails/examples/youtube-thumbnail-size)**.

#### 📦 YouTube thumbnail rows at a glance

**Returned data**

- The submitted video reference and its canonical video ID.
- The quality you requested and the quality that was delivered.
- A direct source-hosted thumbnail URL and its width and height in pixels.
- Optional public title, channel, and publication date data.
- Optional direct links for other available thumbnail qualities.

The image link points to the source thumbnail, so Actor-hosted storage is not the delivery path. If a reference is unavailable, the run reports that item and continues with the other submitted references.

#### ▶️ Run a YouTube thumbnail download

**Quick start**

1. Add one or more public YouTube links or bare video IDs.
2. Choose the thumbnail quality to request.
3. Turn on quality fallback if a lower quality is acceptable when the requested one is missing.
4. Turn on video context or other quality links when you need them.
5. Start the run and open the default dataset.

#### ⚙️ Input

Add one or more public YouTube video references. The Actor accepts common watch, short-link, Shorts, embed, live, legacy, and YouTube Kids links when they resolve to a video. Bare video IDs are also accepted.

**Input fields**

| Field | Type | What it does |
| --- | --- | --- |
| `videoReferences` | array of strings | Lists public YouTube links or bare video IDs to process. |
| `videoReferences[]` | string | One public YouTube link or bare video ID. |
| `quality` | string | Chooses the requested quality: `maxresdefault`, `sddefault`, `hqdefault`, `mqdefault`, or `default`. The default is `hqdefault`. |
| `allowQualityFallback` | boolean | When `true`, tries a lower quality if the requested quality is not available. The result reports the quality delivered. The default is `false`. |
| `includeVideoContext` | boolean | When `true`, adds the public video title, channel, and publication date. The default is `false`. |
| `includeAvailableQualities` | boolean | When `true`, adds direct links for other available thumbnail qualities. The default is `false`. |

**Example default input**

This example uses the default input values.

```json
{
  "videoReferences": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "quality": "hqdefault",
  "allowQualityFallback": false,
  "includeVideoContext": false,
  "includeAvailableQualities": false
}
```

#### 🧾 Output

Each successful dataset row uses the shape below. The two optional groups can be included when their matching input choices are on.

**Dataset link**

The Actor output includes a link to the default dataset.

| Field | Type | What it does |
| --- | --- | --- |
| `dataset` | URL string | Opens the default dataset that contains the thumbnail rows. |

**Output fields**

| Field | Type | What it does |
| --- | --- | --- |
| `videoReference` | string | The YouTube link or video ID that led to the row. |
| `videoId` | string | The canonical YouTube video ID. |
| `requestedQuality` | string | The thumbnail quality requested for the video. |
| `deliveredQuality` | string | The thumbnail quality delivered for the video. |
| `thumbnailUrl` | URL | A direct URL to the selected thumbnail on YouTube. |
| `dimensions` | object | The selected thumbnail's pixel dimensions. |
| `dimensions.width` | integer | The thumbnail width in pixels. |
| `dimensions.height` | integer | The thumbnail height in pixels. |
| `videoContext` | object, optional | Public video context when requested. |
| `videoContext.title` | string | The public video title. |
| `videoContext.channel` | string | The public channel that posted the video. |
| `videoContext.publishedAt` | date-time string | The date and time when the video was published. |
| `availableQualities` | array, optional | Direct links to other available thumbnail qualities when requested. |
| `availableQualities[].quality` | string | The other available thumbnail quality. |
| `availableQualities[].url` | URL | A direct URL to the thumbnail at that quality. |

**Example complete row**

This genuine row shows video context and other available quality links. It is not shortened.

```json
{
  "videoReference": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
  "videoId": "dQw4w9WgXcQ",
  "requestedQuality": "maxresdefault",
  "deliveredQuality": "maxresdefault",
  "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg",
  "dimensions": {
    "width": 1280,
    "height": 720
  },
  "videoContext": {
    "title": "Rick Astley - Never Gonna Give You Up (Official Video) (4K Remaster)",
    "channel": "Rick Astley",
    "publishedAt": "2009-10-25T06:57:33.000Z"
  },
  "availableQualities": [
    {
      "quality": "sddefault",
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/sddefault.jpg"
    },
    {
      "quality": "hqdefault",
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/hqdefault.jpg"
    },
    {
      "quality": "mqdefault",
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/mqdefault.jpg"
    },
    {
      "quality": "default",
      "url": "https://i.ytimg.com/vi/dQw4w9WgXcQ/default.jpg"
    }
  ]
}
```

#### 💳 Pricing

This Actor uses pay-per-event pricing. The primary event is `youtube-thumbnail-retrieved` and costs `$0.0027` for one successful public thumbnail retrieval with its direct source URL. This event applies only when the Actor successfully retrieves a public thumbnail and its direct source URL.

#### 🔌 Integrations

**Dataset and API**

Open the output in the default Apify dataset. You can start runs with the Apify API or read the saved dataset through the API.

**Video guide**

This video shows an Apify integration workflow:

https://www.youtube.com/watch?v=bNACk1\_S\_6w\&list=PLObrtcm1Kw6MUrlLNDbK9QRg8VDJg0gOW\&index=4

#### ❓ FAQ

##### What happens if the requested quality is not available?

With quality fallback off, that item fails when the requested quality is unavailable. With fallback on, the Actor tries a lower available quality and puts the delivered quality in `deliveredQuality`.

##### How can I see which quality was delivered?

Read `deliveredQuality` in the row. It shows the quality of the thumbnail URL in `thumbnailUrl`.

##### Can I get more than one quality link?

Yes. Turn on `includeAvailableQualities` to add direct links for other qualities that are available for the video.

##### Can I add public video context?

Yes. Turn on `includeVideoContext` to add the public title, channel, and publication date.

##### Why did a reference not produce a thumbnail?

A public thumbnail may be unavailable, or the video may be private, deleted, login-gated, or otherwise unable to provide a usable public thumbnail. The run reports the unavailable item and continues with the other references.

##### Can I submit Shorts or bare video IDs?

Yes. The input accepts Shorts links and bare 11-character video IDs, along with the other common public YouTube video link forms.

##### Does the Actor search for videos?

No. Add the public video links or IDs you want to process. The Actor does not search YouTube or discover videos from channels, feeds, or keywords.

##### Do I need a YouTube API key or login?

No. The Actor uses public thumbnail access and does not ask for a customer-supplied YouTube API key or source login.

##### Does the Actor store the image?

No. The result gives you a direct source-hosted thumbnail URL. Actor-hosted storage is not the delivery path.

##### Can I process several videos in one run?

Yes. Add a list of video references. Each successful reference gets its own dataset row.

### 📝 Changelog

**0.0: Initial release**

### 🆘 Support

For issues, questions, or feature requests, [file a ticket](https://console.apify.com/actors/maximedupre~youtube-thumbnails/issues) and I'll fix or implement it in less than 24h 🫡

### 🔗 Related Actors

**Owned actors**

- [YouTube Shorts Downloader](https://apify.com/maximedupre/youtube-shorts-downloader): Get media links and metadata, including thumbnails, from known public Shorts.
- [YouTube Description Extractor](https://apify.com/maximedupre/youtube-description-extractor): Collect public video descriptions, thumbnails, titles, and source links for content review.

**Other thumbnail tools**

- [YouTube Thumbnail Scraper & Downloader](https://apify.com/codenest/youtube-thumbnail-scraper-downloader): Compare another tool for extracting and downloading thumbnails from YouTube videos.
- [YouTube Thumbnail Downloader](https://apify.com/moving_beacon-owner1/my-actor-73): Choose common thumbnail qualities for downloads from multiple video URLs.
- [YouTube Thumbnail Downloader](https://apify.com/parsebird/youtube-thumbnail-downloader): Download thumbnails in bulk with quality fallback and metadata.

**Made with ❤️ by Maxime Dupré**

# Actor input Schema

## `videoReferences` (type: `array`):

Add one or more public YouTube video links or bare video IDs. Common watch, short-link, Shorts, embed, live, legacy, and YouTube Kids links are accepted when they resolve to a video.

## `quality` (type: `string`):

Choose the thumbnail quality to request. If it is not available, the item fails unless quality fallback is on.

## `allowQualityFallback` (type: `boolean`):

When on, use a lower quality if the requested quality is not available. The result reports the quality that was delivered.

## `includeVideoContext` (type: `boolean`):

When on, add the public video title, channel, and publication date to each result.

## `includeAvailableQualities` (type: `boolean`):

When on, add direct links for other available thumbnail qualities along with the selected quality.

## Actor input object example

```json
{
  "videoReferences": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ],
  "quality": "hqdefault",
  "allowQualityFallback": false,
  "includeVideoContext": false,
  "includeAvailableQualities": false
}
```

# Actor output Schema

## `dataset` (type: `string`):

Open the thumbnail results in the default dataset.

# 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 '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "videoReferences": [
        "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("maximedupre/youtube-thumbnails").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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "videoReferences": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"] }

# Run the Actor and wait for it to finish
run = client.actor("maximedupre/youtube-thumbnails").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "videoReferences": [
    "https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  ]
}' |
apify call maximedupre/youtube-thumbnails --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,maximedupre/youtube-thumbnails"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/hmpjZcQTF6LJEPaM8/builds/gfb6gzjurFOBh2sYa/openapi.json