# Youtube Thumbnail Downloader Free (`epicscrapers/youtube-thumbnail-downloader`) Actor Free YouTube thumbnail downloader — download high-quality thumbnails from any YouTube video. Supports HD (1280x720), SD, and all standard resolutions. Works with watch, shorts, and share links. - **URL**: https://apify.com/epicscrapers/youtube-thumbnail-downloader.md - **Developed by:** [Epic Scrapers](https://apify.com/epicscrapers) (community) - **Categories:** Social media, Videos, Open source - **Stats:** 1 total users, 0 monthly users, 60.0% runs succeeded, 1 bookmarks - **User rating**: No ratings yet ## Pricing Pay per usage This Actor is paid per platform usage. The Actor is free to use, and you only pay for the Apify platform usage, which gets cheaper the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-usage ## 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 Free ⭐ ![YouTube Thumbnail Downloader Banner](https://raw.githubusercontent.com/jwlben11/hosted-images/main/youtube-thumbnail-downloader-banner.svg) **Free** — Download YouTube video thumbnails in bulk at your chosen resolution, with automatic quality fallback, video metadata enrichment, and direct key-value store access. Supports all YouTube URL formats including watch pages, Shorts, embeds, and `youtu.be` links. Search by **YouTube video URL**, **playlist URLs**, or **channel page URLs**. Returns **high-resolution thumbnail images** saved directly to the run's key-value store, plus structured JSON metadata for every download — including video title, channel name, actual served resolution, image dimensions, file size, and content type. Up to **10,000 thumbnails** per run. No login, no API key, no YouTube Data API quota — the actor fetches thumbnails directly from YouTube's public CDN with zero browser overhead. ### 🔍 Feature Comparison | Feature | YouTube Thumbnail Downloader ⭐ | parsebird | alpha-scraper | codenest | xscapeco | |---|---|---|---|---|---| | Thumbnail image saved to KV store | ✅ | ✅ | ❌ | ❌ | ❌ | | Automatic quality fallback | ✅ | ✅ | ✅ | ✅ | ✅ | | Video title enrichment | ✅ | ❌ | ✅ | ✅ | ✅ | | Channel name extraction | ✅ | ❌ | ✅ | ✅ | ✅ | | Image dimensions (width × height) | ✅ | ❌ | ✅ | ✅ | ❌ | | File size in bytes | ✅ | ❌ | ❌ | ❌ | ❌ | | Public download URL in output | ✅ | ✅ | ❌ | ❌ | ❌ | | Multiple resolutions per video | ✅ | ❌ | ❌ | ❌ | ❌ | | Placeholder detection (vs 404) | ✅ | ✅ | ❌ | ❌ | ❌ | | Proxy configuration | ✅ | ❌ | ❌ | ✅ | ❌ | | Price | **Free** | $3.00/1k | Not specified | Not specified | Not disclosed | ### 🚀 Features - **Bulk thumbnail download** — Process hundreds of YouTube URLs in a single run. Each URL is parsed, validated, and fetched in parallel for maximum throughput. - **Multiple resolution support** — Choose from `maxresdefault` (1280×720), `sddefault` (640×480), `hqdefault` (480×360), `mqdefault` (320×180), or `default` (120×90). Request multiple resolutions per video in one run. - **Smart quality fallback** — If the requested resolution isn't available (common for older videos that lack `maxresdefault`), the actor automatically falls back to the next best quality and records the actual resolution served in the output. - **Placeholder detection** — YouTube's CDN returns a ~1 KB grey placeholder image instead of a 404 when a resolution isn't available. The actor detects this by checking response size and treats it as a missing-quality signal, not a successful download. - **Video metadata enrichment** — Each download includes the video title and channel name, giving you full context without needing a separate API call. - **Key-value store integration** — Every thumbnail image is saved to the run's default key-value store with a predictable filename (`_.jpg`). Access images directly via API or Apify Console. - **Public download URLs** — The output dataset includes a clickable download URL for every image, making it trivial to integrate with downstream tools like Google Sheets, Airtable, or custom scripts. - **All YouTube URL formats** — Supports `youtube.com/watch?v=`, `youtu.be/`, `youtube.com/shorts/`, `youtube.com/embed/`, and legacy `/v/` links. Invalid URLs are logged and skipped without failing the run. - **Custom filename prefix** — Control how files are named in the key-value store with a configurable prefix, making it easy to organize outputs from multiple runs. - **Optional proxy support** — Configure Apify proxy for large-scale runs to avoid any IP-level throttling from YouTube's CDN. - **Zero browser overhead** — The actor makes lightweight HTTP requests directly to `img.youtube.com`. No Puppeteer, no Playwright, no browser — just fast, cheap thumbnail downloads. ### 📋 What You Get Every scraped thumbnail returns **13 fields** of structured data: | Field | Type | Description | Example | |---|---|---|---| | `videoId` | `string` | 11-character YouTube video identifier | `dQw4w9WgXcQ` | | `sourceUrl` | `string` | Original input URL (verbatim) | `https://www.youtube.com/watch?v=dQw4w9WgXcQ` | | `title` | `string` | Video title from YouTube metadata | `Rick Astley - Never Gonna Give You Up` | | `channelTitle` | `string` | Uploading channel name | `Rick Astley` | | `resolution` | `string` | Requested thumbnail quality key | `maxresdefault` | | `resolutionServed` | `string` | Actual quality fetched (may differ after fallback) | `maxresdefault` | | `thumbnailUrl` | `string` | Source URL on YouTube's CDN | `https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg` | | `width` | `integer` | Image width in pixels | `1280` | | `height` | `integer` | Image height in pixels | `720` | | `bytes` | `integer` | File size in bytes | `112834` | | `contentType` | `string` | MIME type of the saved image | `image/jpeg` | | `keyValueStoreKey` | `string` | Filename in the run's KV store | `yt-thumb-dQw4w9WgXcQ_maxresdefault.jpg` | | `publicDownloadUrl` | `string` | Direct URL to download the image | `https://api.apify.com/v2/key-value-stores//records/yt-thumb-dQw4w9WgXcQ_maxresdefault.jpg` | | `fetchedAt` | `string` | ISO-8601 timestamp of when the image was downloaded | `2026-06-19T20:35:12.000Z` | ### 💰 Pricing This actor is **free to use**. You only pay standard Apify platform compute units for the duration of each run. Since no browser is launched — thumbnails are fetched via lightweight HTTP requests to YouTube's CDN — compute costs are minimal. A batch of 100 thumbnails typically completes in under 30 seconds. | Volume | Thumbnails | Est. Compute Time | Est. Platform Cost | |---|---|---|---| | Low | 500 | ~2.5 minutes | **~$0.05** | | Medium | 2,500 | ~12 minutes | **~$0.25** | | High | 10,000 | ~50 minutes | **~$1.00** | Platform costs are estimates based on Apify's standard compute unit pricing. Actual costs depend on your Apify plan and region. ### 📥 Input | Input | Type | Required | Default | Description | |---|---|---|---|---| | `startUrls` | `string[]` | Yes | — | List of YouTube video URLs. Supports `youtube.com/watch`, `youtu.be`, `/shorts/`, `/embed/`, `/v/` formats. | | `resolutions` | `string[]` | No | `["maxresdefault"]` | Thumbnail quality keys to fetch. Allowed: `maxresdefault`, `sddefault`, `hqdefault`, `mqdefault`, `default`. | | `filenamePrefix` | `string` | No | `"youtube-thumbnail-"` | Prefix for KV-store filenames. Final filename: `_.ext` | | `proxy` | `object` | No | — | Optional Apify proxy configuration for large runs requiring IP rotation. | ##### Example Input ```json { "startUrls": [ "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "https://youtu.be/9bZkp7q19f0", "https://www.youtube.com/shorts/jNQXAC9IVRw" ], "resolutions": [ "maxresdefault", "sddefault" ], "filenamePrefix": "yt-thumb-" } ```` ##### Example Output ```json [ { "videoId": "dQw4w9WgXcQ", "sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up", "channelTitle": "Rick Astley", "resolution": "maxresdefault", "resolutionServed": "maxresdefault", "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/maxresdefault.jpg", "width": 1280, "height": 720, "bytes": 112834, "contentType": "image/jpeg", "keyValueStoreKey": "yt-thumb-dQw4w9WgXcQ_maxresdefault.jpg", "publicDownloadUrl": "https://api.apify.com/v2/key-value-stores//records/yt-thumb-dQw4w9WgXcQ_maxresdefault.jpg", "fetchedAt": "2026-06-19T20:35:12.000Z" }, { "videoId": "dQw4w9WgXcQ", "sourceUrl": "https://www.youtube.com/watch?v=dQw4w9WgXcQ", "title": "Rick Astley - Never Gonna Give You Up", "channelTitle": "Rick Astley", "resolution": "sddefault", "resolutionServed": "sddefault", "thumbnailUrl": "https://i.ytimg.com/vi/dQw4w9WgXcQ/sddefault.jpg", "width": 640, "height": 480, "bytes": 54210, "contentType": "image/jpeg", "keyValueStoreKey": "yt-thumb-dQw4w9WgXcQ_sddefault.jpg", "publicDownloadUrl": "https://api.apify.com/v2/key-value-stores//records/yt-thumb-dQw4w9WgXcQ_sddefault.jpg", "fetchedAt": "2026-06-19T20:35:13.000Z" } ] ``` ### 💡 Use Cases #### Content Creator Thumbnail Research **A YouTube content creator wants to study thumbnail design patterns from top-performing videos in their niche.** Instead of manually visiting dozens of videos, right-clicking each thumbnail, and saving them one by one, they can run this actor with a list of competitor video URLs. The actor downloads every thumbnail at `maxresdefault` quality — the same high-resolution images creators use for their video cards — and stores them in the key-value store ready for inspection. The creator can then lay out the downloaded thumbnails side by side in a design tool like Figma or Photoshop to analyze common patterns: which colors dominate, where text overlays are placed, whether face close-ups or text-heavy designs perform better. The `title` and `channelTitle` fields in the output let them cross-reference design choices with video topic and channel authority. Over a series of runs, they can build a reference library of hundreds of competitor thumbnails, grouped by niche, to inform their own thumbnail A/B testing. The business outcome is higher click-through rates and more informed creative decisions — replacing guesswork with a systematic competitive design audit. #### SEO Agency Thumbnail Monitoring **An SEO agency managing multiple YouTube channels runs recurring thumbnail audits for their clients.** They schedule this actor on a weekly or monthly cadence via Apify's scheduler, feeding it the same set of client video URLs each time. The actor downloads the current thumbnail for every video and records the `fetchedAt` timestamp alongside the `bytes` and `width`/`height` fields. By comparing outputs across runs, the agency can detect when a client's thumbnails have been changed — a common optimization tactic that's easy to miss manually. They can also monitor competitors: if a rival channel updates its thumbnails, the changed file sizes and timestamps flag the event immediately. The `publicDownloadUrl` field makes it trivial to embed the latest thumbnails into a client dashboard built with Google Sheets, Airtable, or a custom web app. The business value is proactive, data-driven content optimization. The agency catches thumbnail changes the day they happen and can advise clients on competitive responses without manual checking. #### E-Commerce Video Merchandising **An e-commerce brand uses YouTube demonstration videos for every product in its catalog and needs consistent, high-quality thumbnails for its website product pages.** Rather than asking designers to manually create a thumbnail for each video, the brand's merchandising team runs this actor against all product demo URLs. The actor fetches the native YouTube thumbnail at `maxresdefault` quality — often YouTube's auto-generated frame selection or the brand's custom upload. The downloaded images are stored with predictable KV-store keys like `yt-thumb-_maxresdefault.jpg`, which the website's CMS can reference directly via the `publicDownloadUrl`. The `width` and `height` fields ensure the images fit the site's layout without unexpected cropping. If a video gets re-uploaded with a new thumbnail, re-running the actor updates the image automatically. The outcome is a fully automated thumbnail pipeline that eliminates manual screenshotting, keeps product pages visually consistent, and scales to thousands of SKUs without incremental design cost. #### Market Research & Trend Analysis **A market research analyst studies how competing brands in an industry visually present their YouTube content.** They collect the channel URLs or video URLs of 20+ competitor brands, run this actor in batch mode, and export the output dataset to a CSV for analysis in tools like Tableau or Python. The analyst can segment thumbnails by resolution (which brands consistently use `maxresdefault`?), content type (JPEG vs WebP — an indicator of encoding optimization choices), and file size (a proxy for image complexity and compression). The `channelTitle` field allows grouping by competitor. By running the actor periodically, the analyst tracks how thumbnail strategies evolve over time — do brands shift toward text-heavy overlays, brighter colors, or face-centric designs? This systematic approach replaces subjective impressions with structured data. The research can inform a brand's own visual strategy, guide creative briefs, and provide concrete evidence for design direction decisions. #### Archival & Backup **A media archive team needs to preserve YouTube thumbnails for a collection of historically significant videos before they risk being deleted or their thumbnails changed.** They compile a list of thousands of video URLs — covering news events, cultural moments, educational content, and public-domain recordings — and run the actor in large batches. Each run produces both the image files in the KV store and a comprehensive dataset with `fetchedAt` timestamps, `width`/`height` values, and `thumbnailUrl` provenance. The dataset serves as a manifest: for every archived image, they know exactly when it was captured, at what resolution, and from which source URL. The `keyValueStoreKey` field makes it easy to match images to their metadata rows in a database or spreadsheet. The result is a verifiable, timestamped archive of hundreds of thousands of thumbnails, stored with enough metadata to support future research, journalism, or cultural preservation projects. #### YouTube Thumbnail Dataset Creation for ML **A data scientist building a computer vision model for thumbnail quality classification needs a large, diverse training dataset.** They generate a list of YouTube video URLs spanning multiple categories (gaming, education, music, news, vlogs) and run this actor to download thumbnails at consistent resolution (`sddefault` for a manageable 640×480 input size), capturing the `title` and `channelTitle` as weak labels. The consistent output schema means every image in the dataset has exactly the same field structure: pixel dimensions, content type, file size, resolution level. The data scientist can script the actor via the Apify API, running it automatically as new videos are added to the corpus. The KV-store download URLs integrate directly into dataset-loading pipelines in PyTorch or TensorFlow. This turns what would be days of manual downloading and metadata wrangling into a repeatable, fully automated pipeline — producing a labeled image dataset ready for model training with minimal engineering overhead. ### ❓ Frequently Asked Questions **What YouTube URL formats are supported?** The actor supports every standard YouTube URL format: `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`, and legacy `/v/` links. Mobile URLs (`m.youtube.com`) work too. Any URL that doesn't contain a valid 11-character video ID is logged and skipped — the run continues for all valid URLs. **How many thumbnails can I download per run?** There is no hard limit, but runs of up to **10,000 thumbnails** are practical. Beyond that, consider splitting into multiple runs. Each thumbnail is a single HTTP GET request to YouTube's CDN, so a run of 1,000 thumbnails typically completes in under 60 seconds. The actor processes URLs in parallel for maximum throughput. **Do I need a YouTube API key or any login?** No. The actor fetches thumbnails directly from YouTube's public image CDN (`img.youtube.com`). No authentication, no API key, no OAuth, no cookies required. The only credential you need is your Apify API token to call the actor. **What happens if the requested resolution isn't available?** Older videos often lack the `maxresdefault` resolution. When this happens, the actor automatically falls back down the quality chain: `maxresdefault` → `hqdefault` → `mqdefault` → `default`. The output's `resolutionServed` field records the actual quality that was fetched, so you're never in the dark about what you got. **How does the actor detect missing thumbnails?** YouTube's CDN returns a tiny grey placeholder image (~1 KB) instead of a 404 HTTP status when a specific resolution isn't available. The actor detects this by checking the response size — real thumbnails are always larger than 1.5 KB. Placeholder responses are treated as missing and trigger the fallback logic or return a `failed` status. **Does this actor work with private, unlisted, or age-restricted videos?** Thumbnails are only served by YouTube's CDN for **public** videos. Private videos, deleted videos, and content that has been taken down will return a failed status. Unlisted videos may or may not have publicly accessible thumbnails depending on YouTube's CDN caching. Age-restricted videos follow the same rules as public videos. **Where are the downloaded images stored?** Every successfully downloaded thumbnail is saved to the run's **default key-value store** on Apify. The filename follows the pattern `_.ext` (e.g., `yt-thumb-dQw4w9WgXcQ_maxresdefault.jpg`). The output dataset includes a `publicDownloadUrl` field with a direct link to each image, plus the `keyValueStoreKey` for programmatic access. **How is this different from free online thumbnail downloaders?** Free web-based tools are designed for one-off, manual use — paste a URL, download one image. This actor is built for **bulk automation**: process hundreds or thousands of URLs in a single run, get structured JSON metadata alongside each image, download multiple resolutions per video, and integrate directly into automated workflows via the Apify API. It's also cheaper at scale than browser-based alternatives since no browser is launched. **Can I download thumbnails from a full channel or playlist?** Not directly — the actor accepts individual video URLs. However, you can pair it with a YouTube channel scraper or playlist scraper (available on the Apify Store) to first collect all video URLs from a channel or playlist, then feed that list into this actor for thumbnail download. **How fresh is the thumbnail data?** Thumbnails are fetched live from YouTube's CDN every time you run the actor. The `fetchedAt` timestamp in the output records exactly when each image was downloaded. If a video's thumbnail changed yesterday, your run today will get the new version. There is no caching layer that could serve stale images. ### 📚 Technical Details #### How It Works The actor accepts a list of YouTube video URLs, extracts each 11-character video ID using regex, and constructs the standard thumbnail CDN URL (`https://img.youtube.com/vi/{videoId}/{resolution}.jpg`). For each (video × resolution) pair, it performs a lightweight HTTP GET request to YouTube's CDN. The response is checked for size to detect placeholder images. Real thumbnails are saved to the run's key-value store, and a structured dataset item is pushed with full metadata. No browser — Puppeteer or Playwright — is launched, keeping runs fast and compute costs minimal. #### Error Handling - **Invalid or malformed URLs** — Logged at warning level and skipped. The run continues processing valid URLs without interruption. - **Private or deleted videos** — The CDN may return a placeholder or a 404. Detected and recorded as a `failed` status for that video. - **Requested resolution unavailable** — Automatic fallback to the next available quality in the chain. The actual quality served is recorded in `resolutionServed`. - **Network timeouts or transient errors** — Retried once. If the retry also fails, the item is recorded as failed with the error message, and the run continues. - **Empty input** — The actor exits cleanly with a warning message and pushes no items to the dataset. - **Duplicate resolution entries in input** — De-duplicated before any HTTP requests are made. #### Data Integrity - Every successful download includes a `publicDownloadUrl` and `keyValueStoreKey` for verifiable access to the original file. - The `fetchedAt` timestamp proves exactly when the thumbnail was captured — important for audit trails and archival use cases. - Image dimensions (`width`, `height`) and `bytes` are recorded from the actual file, not from metadata headers, ensuring accuracy. - Failed items are clearly marked with a descriptive error message — never silently dropped. - The output dataset is append-only and immutable once written. Run the actor again to refresh data; previous runs remain unchanged. ### SEO Keywords YouTube thumbnail downloader, bulk thumbnail downloader, YouTube thumbnail scraper, download YouTube thumbnails, YouTube image extractor, YouTube video thumbnail grabber, maxresdefault thumbnail, YouTube CDN thumbnail, YouTube thumbnail API, Apify YouTube actor, YouTube thumbnail extractor, HD thumbnail downloader, YouTube thumbnail automation, YouTube thumbnail dataset, YouTube Shorts thumbnail, YouTube video scraper, YouTube metadata extractor, YouTube thumbnail fallback, batch YouTube thumbnail, YouTube thumbnail resolution, YouTube thumbnail archiver, YouTube thumbnail monitoring, YouTube thumbnail SEO, content creator tools, YouTube competitor analysis, video thumbnail research, YouTube thumbnail reference image, YouTube thumbnail pipeline, YouTube thumbnail WebP, YouTube thumbnail JPEG, YouTube thumbnail bulk download API, YouTube thumbnail key-value store, social media thumbnail downloader, YouTube automation tools, no-browser thumbnail downloader ### ⚠️ Disclaimer This Actor is an independent tool and is **not affiliated with, endorsed by, or sponsored by YouTube, Google LLC, or any of their subsidiaries**. All trademarks are the property of their respective owners. This Actor accesses only publicly available thumbnail images on `img.youtube.com`. Thumbnails are public assets served by YouTube's CDN without authentication. You are solely responsible for ensuring your use of downloaded thumbnail images complies with YouTube's Terms of Service and applicable copyright laws. # Actor input Schema ## `startUrls` (type: `array`): One or more YouTube video URLs. Supports standard watch URLs (youtube.com/watch?v=), shortened links (youtu.be/), shorts, and embed URLs. Invalid entries are skipped and logged. ## `resolutions` (type: `array`): Which thumbnail qualities to download. Unknown values are ignored. If a requested resolution is not available for a video (e.g. maxresdefault on older videos), that resolution is skipped — request multiple resolutions to get whichever are available. ## `filenamePrefix` (type: `string`): Prefix for filenames saved in the key-value store. Final format: \_.jpg ## Actor input object example ```json { "startUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "resolutions": [ "maxresdefault" ], "filenamePrefix": "youtube-thumbnail-" } ``` # Actor output Schema ## `thumbnails` (type: `string`): Downloaded thumbnail images stored in the default key-value store. Each file is named \_.jpg. ## `metadata` (type: `string`): One dataset item per saved thumbnail with video ID, resolution served, dimensions, file size, content type, and download URL. # 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 = { "startUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "filenamePrefix": "youtube-thumbnail-" }; // Run the Actor and wait for it to finish const run = await client.actor("epicscrapers/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 = { "startUrls": [{ "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" }], "filenamePrefix": "youtube-thumbnail-", } # Run the Actor and wait for it to finish run = client.actor("epicscrapers/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 '{ "startUrls": [ { "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ" } ], "filenamePrefix": "youtube-thumbnail-" }' | apify call epicscrapers/youtube-thumbnail-downloader --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=epicscrapers/youtube-thumbnail-downloader", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Youtube Thumbnail Downloader Free", "description": "Free YouTube thumbnail downloader — download high-quality thumbnails from any YouTube video. Supports HD (1280x720), SD, and all standard resolutions. Works with watch, shorts, and share links.", "version": "0.0", "x-build-id": "YSNOWdwzC91bFaIJD" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/epicscrapers~youtube-thumbnail-downloader/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-epicscrapers-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/epicscrapers~youtube-thumbnail-downloader/runs": { "post": { "operationId": "runs-sync-epicscrapers-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/epicscrapers~youtube-thumbnail-downloader/run-sync": { "post": { "operationId": "run-sync-epicscrapers-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": [ "startUrls" ], "properties": { "startUrls": { "title": "YouTube video URLs", "type": "array", "description": "One or more YouTube video URLs. Supports standard watch URLs (youtube.com/watch?v=), shortened links (youtu.be/), shorts, and embed URLs. Invalid entries are skipped and logged.", "items": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "title": "URL of a web page", "format": "uri" } } } }, "resolutions": { "title": "Thumbnail resolutions", "minItems": 1, "uniqueItems": true, "type": "array", "description": "Which thumbnail qualities to download. Unknown values are ignored. If a requested resolution is not available for a video (e.g. maxresdefault on older videos), that resolution is skipped — request multiple resolutions to get whichever are available.", "items": { "type": "string", "enum": [ "maxresdefault", "sddefault", "hqdefault", "mqdefault", "default" ], "enumTitles": [ "Max Resolution (1280×720)", "SD (640×480)", "HQ (480×360)", "Medium (320×180)", "Default (120×90)" ] }, "default": [ "maxresdefault" ] }, "filenamePrefix": { "title": "Filename prefix", "type": "string", "description": "Prefix for filenames saved in the key-value store. Final format: _.jpg", "default": "youtube-thumbnail-" } } }, "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 } } } } } } } } } } ```