Send the video title and host details as JSON, get back a 1280x720 thumbnail PNG.
Prefer to try it in your browser first? Open the YouTube Thumbnail tool.
Education channels and high-volume creators use the YouTube thumbnail generator API to ship one polished thumbnail per video without booking design time per upload. The 1280x720 size meets YouTube's upload spec exactly, and the layout reserves the bottom-right corner so the duration badge does not overlap with copy. You post the title, host avatar URL, and brand inputs as JSON, and the response holds a PNG ready to upload via the Data API or the YouTube Studio dashboard.
curl -X POST https://app.html2img.com/api/v1/templates/youtube-thumbnail \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"title":"I built a $0 SaaS in 7 days","eyebrow":"CASE STUDY","duration":"14:22","host_name":"Devon Reed","host_avatar_url":"https://i.pravatar.cc/160?img=33","background_image_url":"https://picsum.photos/seed/yt-thumb/1280/720","background_color":"#0F172A","accent_color":"#FACC15"}'
A single cURL call to render a YouTube Thumbnail as a PNG. Add "format": "pdf" to the payload to get a PDF instead. For the full PHP, Node and Python equivalents, plus every input the template accepts, see the
YouTube Thumbnail API reference.
Setting up your key is covered in the
authentication guide.
View the YouTube Thumbnail API reference: inputs, defaults, error responses and cURL, PHP, Node and Python code samples. Read the docs.
Daily news channels and education creators pushing 5+ videos a week cannot design each thumbnail by hand. Pull the episode metadata from your CMS, post to this endpoint, and use the resulting URL as the upload thumbnail via the YouTube Data API. Halberd Software's technical channel publishes 2 to 3 explainers per week through this exact pipeline, with thumbnails matching the channel's editorial style every time.
Audio-first shows that publish video versions to YouTube benefit from thumbnails that read as podcast content rather than as standard YouTube fare. Render with the episode title, the host's photo, and the show name in the eyebrow slot, and the YouTube subscribers see consistent branding. Wren Analytics ships a daily podcast to YouTube with rendered thumbnails that take 2 seconds each in the publishing pipeline.
Course platforms publish dozens of lesson videos with consistent branding requirements. Render thumbnails per lesson with the lesson number, course name, and module color, upload via the Data API, and the course page on YouTube reads as a structured curriculum rather than a series of one-off videos. Linden & Co's coding course publishes 80 lessons through this template.
Breaking news teams need a thumbnail that looks editorial but goes live within minutes of the video being ready. Render with the headline, eyebrow ("Breaking", "Update", "Analysis"), and a hero photo URL pulled from the wire image system. The thumbnail is ready before the video has finished encoding, so no upload time is lost waiting on design.
B2B SaaS marketing teams publish weekly product demo videos and want each thumbnail to reflect the feature being demoed. Render with the feature name and a 16:9 screenshot, upload, and the demo library reads as a structured showcase rather than a YouTube playlist with mixed visual treatments. Northwind Studio's 40-video demo library all uses this template.
Matches the spec at YouTube thumbnail dimensions and constraints.
These specifications describe the default PNG output. The template can also return a PDF document with selectable text through the HTML to PDF API: set format to pdf in the request. See the format parameter docs for how PDF output behaves.
POST to the template endpoint with the values you want rendered. Authenticate with your API key.
The template is rendered server-side as a 1280x720 PNG, or as a PDF document if you set format to pdf.
Cache it, embed it in your page, attach it to an email.
Subtle gradients that read fine on the static thumbnail get washed out when YouTube layers its red play button or pink hover state on top. Use accent_color values with a contrast ratio above 4.5 against the background so the thumbnail survives the player overlay without looking muddy.
Text or hero faces in the bottom-right corner get covered by the duration badge in the YouTube grid. Keep the focal area inside the upper 80 percent of the canvas, and reserve the bottom-right corner for low-priority content like a small brand mark.
YouTube caps thumbnail uploads at 2 MB. Hi-DPI renders or thumbnails with very dense photographic backgrounds can exceed this. Stick with default DPI, and if a particular render approaches the cap, reduce JPEG-equivalent visual complexity by simplifying the background.
A quick summary of what the YouTube Thumbnail template accepts. The full reference, with example values and array shapes, is in the docs.
| Name | Type | Required |
|---|---|---|
title | string | Required |
eyebrow | string | Optional |
duration | string | Optional |
host_name | string | Optional |
host_avatar_url | url | Optional |
background_image_url | url | Optional |
background_color | string | Optional |
accent_color | string | Optional |
See the full inputs reference for descriptions, examples and validation rules.
Other templates in the social media category.
Bold share images sized for Facebook feed posts
Bold square images sized for the Instagram feed
Vertical 9:16 covers for Instagram and TikTok stories
Polished share images sized for LinkedIn feed posts
Vertical 2:3 pins with strong typography that stand out in feed
Render a tweet-style card from supplied data — avatar, body, image, metrics
Generate share-ready images sized for Twitter/X posts
A starting point from each of the other two template categories.
See the full template gallery for every design grouped by category.
What size is a YouTube thumbnail?
YouTube wants 1280x720 (16:9) under 2 MB. This template enforces both. Anything smaller than 640x360 fails YouTube's minimum dimension check, and anything over 2 MB gets rejected at upload time.
Why is my thumbnail rejected?
The two common causes are file size over 2 MB and aspect ratio that is not 16:9. This template stays within both limits by default. If you customize width and height, double-check the result before piping into the upload step.
What text shows in the YouTube grid?
YouTube renders the video title and channel name as separate text below the thumbnail. The thumbnail itself should not just duplicate the title. Use the thumbnail for visual hook and emotional cue, while the title carries the precise topic.
How do I avoid the duration badge covering my text?
YouTube places the duration badge in the bottom-right corner. Keep important content in the upper-left 75 percent of the canvas. The template applies a subtle visual hierarchy that respects this safe zone.
Can I use this for YouTube Shorts?
No, Shorts use a 1080x1920 vertical thumbnail. This template renders 16:9 horizontal which is the correct ratio for standard videos. For Shorts artwork, use the instagram-story template at 1080x1920 instead.
Does this support face cutouts or arrows?
Not directly. Supply a hero_image_url with a transparent background and the renderer composites it into the thumbnail. Arrows and graphic overlays are out of scope for this template, and adding them post-render in your editor stays the cleaner path.
25 renders a month on the free tier. See the pricing page for higher-volume plans.