# YouTube Thumbnail Downloader & Scraper ✅ Bulk (`atomus/youtube-thumbnail-downloader`) Actor Download YouTube thumbnails in bulk. Paste video links, Shorts, youtu.be links, embeds or bare video ids, mixed freely. Shorts come back vertical in their real shape, not padded into a wide frame. Every row carries the title, channel, pixel size and the image file. No cookies, no API key. - **URL**: https://apify.com/atomus/youtube-thumbnail-downloader.md - **Developed by:** [Atomus APIs](https://apify.com/atomus) (community) - **Categories:** Videos, Social media - **Stats:** 3 total users, 2 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: 5.00 out of 5 stars ## Pricing from $2.00 / 1,000 thumbnail returneds This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event ## What's an Apify Actor? An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes. 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. Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md. ## 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. Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run. For examples already wired to this Actor's own input schema, see the [API](#api) section below. Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`). # README ## YouTube Thumbnail Downloader & Scraper
YOUTUBE THUMBNAIL DOWNLOADER  •  YOUTUBE THUMBNAIL API

Get the whole picture,
not the cropped one.

Paste YouTube links and get every thumbnail back as a real image file, with the video title and channel on the same row. Shorts come back vertical, in their real shape, instead of squeezed into a wide frame with filler down both sides, and old uploads with no HD thumbnail still return an image. Any link shape works: watch pages, Shorts, youtu.be, embeds, or a bare video ID. No YouTube account, no login, no cookies, no API key.

NO THUMBNAIL, NO CHARGE  SHORTS STAY VERTICAL 
#### Copy to your AI assistant Paste this into ChatGPT, Claude, Cursor, or any LLM to start using this Actor right away. ``` atomus/youtube-thumbnail-downloader is an Apify Actor that downloads YouTube video thumbnails in bulk and returns them as both a direct image URL and a stored image file, one row per input link: url, videoId, status, title, channelName, channelUrl, quality (the size actually delivered), width, height, isShort, thumbnailUrl, imageFileUrl, and reason when a link did not work. On the default setting a Short comes back as its real 1080x1920 vertical image, instead of the 1280x720 one where the vertical video sits in a strip down the middle with filler on both sides, and an old upload with no HD thumbnail still returns a picture because the size walks down until one exists. Use it whenever someone needs YouTube thumbnails at scale without cookies, a login, or an API key - thumbnail A/B analysis, competitor research, building video galleries, dataset building, or republishing clips to vertical platforms. Run it with curl: curl -X POST "https://api.apify.com/v2/acts/atomus~youtube-thumbnail-downloader/run-sync-get-dataset-items?token=APIFY_TOKEN" -H "Content-Type: application/json" -d '{"videoUrls":["https://www.youtube.com/watch?v=dQw4w9WgXcQ","https://www.youtube.com/shorts/5mU6SRS2Bxo"],"quality":"best","fallbackToLowerQuality":true,"saveImages":true}'. Or in Python: ApifyClient("APIFY_TOKEN").actor("atomus/youtube-thumbnail-downloader").call(run_input={"videoUrls":[...],"quality":"best"}) then client.dataset(run["defaultDatasetId"]).list_items().items. Inputs: videoUrls (string[], required - watch URL, Shorts URL, youtu.be short link, live URL, embed URL, m.youtube.com, music.youtube.com, youtube-nocookie.com, the old /v/ form, or a bare 11-character video id), quality (enum: best, maxresdefault, sddefault, hqdefault, mqdefault, default - best is the default and is the only one that returns a Short vertically; the fixed sizes are 1280x720, 640x480, 480x360, 320x180 and 120x90 respectively and always come back wide or square), fallbackToLowerQuality (bool, default true), saveImages (bool, default true). Channel, playlist and profile links are rejected locally at no charge. Billing is one thumbnail-scraped event per thumbnail returned; a video with no thumbnail at any size is free, and so is a link that was not a YouTube video. Full input schema, every enum and default, and the complete output field list: GET https://api.apify.com/v2/acts/atomus~youtube-thumbnail-downloader/build/default ``` *** ### YouTube MCP Server: use these Actors from ChatGPT, Claude or Cursor Point your AI assistant at Atomus and it can pull video and social data on its own. No glue code, no scraping logic in your prompts. ```json { "mcpServers": { "atomus": { "url": "https://mcp.apify.com?tools=atomus/youtube-thumbnail-downloader,atomus/tiktok-scraper,atomus/twitter-scraper,atomus/bilibili-scraper,atomus/douyin-scraper", "headers": { "Authorization": "Bearer YOUR_APIFY_TOKEN" } } } } ``` Then ask, in plain language: > "Grab the thumbnails for these twenty videos, tell me which ones are Shorts, and list the titles next to each image." Pinning the `tools=` list is what keeps your assistant on these Actors instead of reaching for whatever scraper it finds first. *** ### How to download YouTube thumbnails #### One video, best quality available The default already does this. It takes the largest picture the video actually has, and walks down a size only if that one is missing. ```json { "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"] } ``` #### Shorts, without the filler down the sides Nothing to configure. A Short returns 1080x1920 and the row is flagged `isShort: true`. ```json { "videoUrls": [ "https://www.youtube.com/shorts/5mU6SRS2Bxo", "https://www.youtube.com/shorts/LiH-P4rSkLI" ] } ``` Ask any other thumbnail tool for these and you get a 1280x720 picture with the vertical video in a strip down the middle and blurred filler on both sides. Two thirds of the image is not the video. #### A batch of links in whatever shape you have them Mix formats freely. Watch pages, Shorts, short links and bare IDs can all sit in the same run. ```json { "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ&t=42s", "https://youtu.be/9bZkp7q19f0", "https://www.youtube.com/shorts/5mU6SRS2Bxo", "https://m.youtube.com/watch?v=kJQP7kOUFXs", "jNQXAC9IVRw" ], "saveImages": true } ``` #### Every image the same size, for a grid or a video wall When your layout needs identical dimensions, pick a fixed size instead of `best`. All of them are wide or square, so a Short will have filler at the sides. That is the trade you are making on purpose here. ```json { "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "quality": "maxresdefault", "fallbackToLowerQuality": true } ``` #### Just the links, no files Turn the files off when you are feeding the URLs into something else and do not need the downloads. ```json { "videoUrls": ["https://www.youtube.com/watch?v=dQw4w9WgXcQ"], "saveImages": false } ``` *** ### Input | Field | Type | Default | What it does | |---|---|---|---| | `videoUrls` | string\[] | required | YouTube video links, in any shape listed below. One per line. | | `quality` | string | `best` | Which picture to take. `best` is the only value that returns a Short vertically. See the table under Output. | | `fallbackToLowerQuality` | boolean | `true` | Use the next smaller size when the one you picked does not exist for that video. | | `saveImages` | boolean | `true` | Save each thumbnail as a real image file with the run, not just its link. | #### Which links work All of these are accepted, and you can mix them in one run: | Shape | Example | |---|---| | Normal video | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` | | Short | `https://www.youtube.com/shorts/5mU6SRS2Bxo` | | Short link | `https://youtu.be/dQw4w9WgXcQ` | | Live | `https://www.youtube.com/live/dQw4w9WgXcQ` | | Embed | `https://www.youtube.com/embed/dQw4w9WgXcQ` | | Mobile | `https://m.youtube.com/watch?v=dQw4w9WgXcQ` | | YouTube Music | `https://music.youtube.com/watch?v=dQw4w9WgXcQ` | | Privacy embed | `https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ` | | Old style | `https://www.youtube.com/v/dQw4w9WgXcQ` | | Bare video ID | `dQw4w9WgXcQ` | Extra bits in the link are fine: `?t=42s`, `&list=...`, and a missing `https://` all still work. **What does not work, and costs you nothing:** a channel link (`/@handle`, `/channel/UC...`, `/c/...`, `/user/...`), a playlist link, or anything that is not a YouTube video. These are rejected before any request is made, and the row tells you which line it was. *** ### What data does the YouTube Thumbnail Downloader return? One row per link you sent in. **The picture** | Field | What it is | |---|---| | `thumbnailUrl` | Direct link to the image on YouTube's servers. It carries no token and does not expire. | | `imageFileUrl` | Link to the image file saved with this run, when `saveImages` is on. | | `quality` | The size actually delivered, which may differ from the one you asked for if the fallback stepped in. | | `width`, `height` | Real pixel size of the image delivered. | | `isShort` | `true` when the original frame is taller than it is wide. | **The video** | Field | What it is | |---|---| | `url` | The link exactly as you sent it, so you can join the results back to your list. | | `videoId` | The 11-character YouTube video ID. | | `title` | The video title. | | `channelName` | The channel that published it. | | `channelUrl` | Link to that channel. | **What happened** | Field | What it is | |---|---| | `status` | `ok`, `not_found` (no thumbnail at any size), `invalid_url` (not a YouTube video link), or `skipped`. | | `reason` | Plain-language explanation, present only when something did not work. | Example row: ```json { "url": "https://www.youtube.com/shorts/5mU6SRS2Bxo", "videoId": "5mU6SRS2Bxo", "status": "ok", "reason": null, "title": "World's Largest Tennis Match", "channelName": "MrBeast", "channelUrl": "https://www.youtube.com/@MrBeast", "quality": "original", "width": 1080, "height": 1920, "isShort": true, "thumbnailUrl": "https://i.ytimg.com/vi/5mU6SRS2Bxo/oar2.jpg", "imageFileUrl": "https://api.apify.com/v2/key-value-stores/.../records/5mU6SRS2Bxo-original.jpg" } ``` #### The sizes | Option | Real size | Shape | |---|---|---| | **Best available** (default) | 1080x1920 on a Short, otherwise 1280x720 | the video's real shape | | Large | 1280x720 | wide | | Medium | 640x480 | 4:3 | | Small | 480x360 | 4:3 | | Tiny | 320x180 | wide | | Icon | 120x90 | 4:3 | *** ### How much does it cost to download YouTube thumbnails? Pay per thumbnail returned: **$8/1k → $2/1k by Apify plan**. You are charged once per thumbnail that actually came back. Three things are free, every time: - a video with no thumbnail at any size (deleted, private, or it never had one) - a link that was not a YouTube video, such as a channel or a playlist - a link the run did not get to There is no minimum per link and no charge for an empty result. That is unusual enough to be worth stating plainly: most scrapers bill a floor per input because their upstream data provider bills them per request whether or not anything comes back. This Actor has no such provider, so there is no floor to pass on. *** ### What do people use the YouTube Thumbnail Downloader for? - **Thumbnail A/B analysis**: pull the thumbnails of your last 200 uploads next to their titles and see which framing, faces and colours line up with your best performers. - **Competitor research**: grab every thumbnail from a list of rival videos and compare their visual pattern against yours. - **Republishing to vertical platforms**: take Shorts thumbnails at their real 9:16 shape, ready for Reels or TikTok, with no cropping step. - **Video galleries and embeds**: build a grid of video cards with a real image behind each one instead of hotlinking. - **Dataset building**: thumbnails plus titles and channels, as structured rows, for computer-vision or content-analysis work. - **Archiving**: keep the image alongside the metadata, so the record survives the video being taken down. - **Content audits at agencies**: one run across a client's whole catalogue, exported with every title and channel attached. *** ### YouTube Thumbnail Downloader vs other thumbnail tools vs the official YouTube API | | This Actor | Other thumbnail downloaders | YouTube Data API | |---|---|---|---| | Shorts in their real vertical shape | **Yes** | No, padded into a wide frame | No | | Old uploads with no HD thumbnail | **Still returns an image** | Often returns nothing | Returns what exists | | Title and channel on the same row | **Yes** | Rarely | Yes, as a separate call | | Link shapes accepted | **10, mixed freely** | Typically 3 or 4 | Video IDs only | | Downloads the image file | **Yes** | Sometimes | No, URLs only | | API key or quota | **None** | None | Key required, daily quota | | Empty result charged | **No** | Varies | Costs quota | The official API is the right tool when you already have a key and want the full metadata catalogue. It hands you thumbnail URLs but never the files, it has a daily quota, and it does not expose a Short's vertical frame at all. *** ### FAQ #### What is a YouTube thumbnail downloader? A tool that takes YouTube video links and returns the preview images YouTube shows for those videos, as files or as direct links, usually in bulk rather than one at a time. #### Do I need a YouTube account, cookies, or an API key? No. Nothing here requires a login, a cookie, or a key of any kind. #### Why do Shorts look wrong in other thumbnail tools? Because a Short is filmed vertically but the thumbnail those tools request is a wide 1280x720 frame. YouTube fits the vertical video into the middle of it and fills both sides, so most of the image is not the video. This Actor also fetches the original uploaded frame, checks that it really is the vertical one, and gives you that instead. A Short comes back at 1080x1920. #### The video is old and has no HD thumbnail. Will it work? Yes. When a size is missing the Actor walks down to the next one instead of giving up, so you get the largest picture that exists rather than an empty row. The first video ever uploaded to YouTube, from 2005, returns an image at 480x360. #### Do the image links expire? No. The links point at YouTube's image servers, carry no token and no signature, and keep working for as long as the video exists. #### Can I get every size for one video? Not in a single row. Run the same link again with a different `quality` if you need more than one. #### What happens to a channel or playlist link? It is rejected immediately, before any request is made, and you are not charged. The row tells you exactly which line it was, which matters when you pasted 500 of them. #### How much does it cost? Per thumbnail returned, $8/1k → $2/1k by Apify plan. Videos with no thumbnail and invalid links are free. #### Can I use this from ChatGPT or Claude? Yes. Use the MCP configuration near the top of this page, or paste the block under "Copy to your AI assistant" into any chat assistant. #### Is it legal to download YouTube thumbnails? The images are served publicly by YouTube without authentication. As with any scraped content, what matters is what you do with it: respect copyright, YouTube's terms, and applicable law. Thumbnails are the creator's work and are not yours to republish as your own. *** ### All Atomus scrapers 2.4M+ RESULTS DELIVERED *** ### Support ### ⚠️ Disclaimer This Actor is an independent tool and is not affiliated with, endorsed by, or sponsored by YouTube or Google. YouTube® is a registered trademark of its respective owner. All trademarks are property of their respective owners. Thumbnails are the work of the creators who uploaded them and remain their property. Use the images and data this Actor returns in compliance with copyright law, applicable data protection laws (GDPR, CCPA) and YouTube's terms of service. Do not use them for spam, harassment, or unlawful purposes. # Actor input Schema ## `videoUrls` (type: `array`): One line per video. Every one of these forms works, and you can mix them freely in the same run: • Normal video: https://www.youtube.com/watch?v=dQw4w9WgXcQ • Short: https://www.youtube.com/shorts/gJPFnmr0ML0 • Short link: https://youtu.be/dQw4w9WgXcQ • Live: https://www.youtube.com/live/dQw4w9WgXcQ • Embed: https://www.youtube.com/embed/dQw4w9WgXcQ • Mobile: https://m.youtube.com/watch?v=dQw4w9WgXcQ • YouTube Music: https://music.youtube.com/watch?v=dQw4w9WgXcQ • Privacy embed: https://www.youtube-nocookie.com/embed/dQw4w9WgXcQ • Old style: https://www.youtube.com/v/dQw4w9WgXcQ • Just the video id: dQw4w9WgXcQ Extra bits in the link are fine: ?t=42s, \&list=..., and a missing https:// all still work. This field takes links to VIDEOS. A channel, playlist or profile link is rejected straight away, at no charge, and the row tells you which line it was. Cost: $8/1k → $2/1k by Apify plan, per thumbnail returned. A video with no thumbnail, a repeated link and a link that is not a YouTube video are all free. ## `quality` (type: `string`): Best available is the right choice for almost everyone. It gives you the largest picture the video has, and when the video is a Short it gives you the real vertical image (1080x1920) instead of the wide one, where the video sits in a strip down the middle with filler on both sides. Pick a fixed size instead when every image has to have identical dimensions, for example a grid or a video wall. Those are always wide or square, so a Short will have filler at the sides. That is the trade you are choosing on purpose. The sizes listed are the real measured ones. Worth knowing: YouTube's own internal names for these do not line up with their size, so if another tool offers you "HD" or "HQ" you may well get the smaller file. ## `fallbackToLowerQuality` (type: `boolean`): Not every video has every size. Older uploads in particular often have only the small ones, and some videos have no HD version at all. Leave this on and you get the next size down instead of an empty row. Turn it off and a video without your exact size is reported as not found. Either way you are never charged for a video that came back with no image. ## `saveImages` (type: `boolean`): On: each thumbnail is saved as a real .jpg file you can open or download straight from this run, and the row also carries a direct link to that file. Off: you get only the link to the picture on YouTube's servers, and downloading it is up to you. Useful if you are feeding the links into something else and do not need the files. Either way the row always tells you which video the picture belongs to. ## Actor input object example ```json { "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://www.youtube.com/shorts/5mU6SRS2Bxo" ], "quality": "best", "fallbackToLowerQuality": true, "saveImages": true } ``` # Actor output Schema ## `results` (type: `string`): No description ## `files` (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 = { "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://www.youtube.com/shorts/5mU6SRS2Bxo" ] }; // Run the Actor and wait for it to finish const run = await client.actor("atomus/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 = { "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://www.youtube.com/shorts/5mU6SRS2Bxo", ] } # Run the Actor and wait for it to finish run = client.actor("atomus/youtube-thumbnail-downloader").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 '{ "videoUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://www.youtube.com/shorts/5mU6SRS2Bxo" ] }' | apify call atomus/youtube-thumbnail-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "type": "http", "url": "https://mcp.apify.com/?tools=fetch-actor-details,atomus/youtube-thumbnail-downloader" } } } ``` 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 ` 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/dAbzaBhxq4rQqbl4a/builds/zqevuOAcYgTwYRyAD/openapi.json