---
title: "YouTube Thumbnail Generator API: 1280x720 PNGs from JSON"
description: "Render thumbnails on demand with the YouTube thumbnail generator API. POST title, host, and a hero photo URL, get back a 1280x720 PNG ready to upload."
url: "https://html2img.com/templates/youtube-thumbnail/"
---

# Youtube Thumbnail Generator API

Send the video title and host details as JSON, get back a 1280x720 thumbnail PNG.

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.

## At a glance

- **Template slug:** `youtube-thumbnail`
- **Category:** social
- **Endpoint:** `POST https://app.html2img.com/api/v1/templates/youtube-thumbnail`
- **Authentication:** `X-API-Key` header
- **Cost:** one credit per render, PNG or PDF
- **Page:** https://html2img.com/templates/youtube-thumbnail/

## Fields

| Field | Type | Required | Example |
| --- | --- | --- | --- |
| `title` | string | Yes | I built a $0 SaaS in 7 days |
| `eyebrow` | string | No | CASE STUDY |
| `duration` | string | No | 14:22 |
| `host_name` | string | No | Devon Reed |
| `host_avatar_url` | url | No | https://i.pravatar.cc/160?img=33 |
| `background_image_url` | url | No | https://picsum.photos/seed/yt-thumb/1280/720 |
| `background_color` | string | No | #0F172A |
| `accent_color` | string | No | #FACC15 |

## Defaults

| Field | Default |
| --- | --- |
| `width` | 1280 |
| `height` | 720 |

## Example request

```bash
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"}'
```

## In your language

### PHP

```php
<?php
$response = \Illuminate\Support\Facades\Http::withHeaders([
    'X-API-Key' => 'YOUR_API_KEY',
])->post('https://app.html2img.com/api/v1/templates/youtube-thumbnail', ['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']);

$url = $response->json('url');
```

### Node.js

```javascript
const response = await fetch('https://app.html2img.com/api/v1/templates/youtube-thumbnail', {
  method: 'POST',
  headers: {
    'X-API-Key': 'YOUR_API_KEY',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    "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"
}),
});

const { url } = await response.json();
```

### Python

```python
import requests

response = requests.post(
    'https://app.html2img.com/api/v1/templates/youtube-thumbnail',
    headers={'X-API-Key': 'YOUR_API_KEY'},
    json={'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'},
)

url = response.json()['url']
```

## What it is for

### High-volume creators auto-generating thumbnails from metadata

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.

### Podcast video hosts cross-posting to YouTube

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.

### Education platforms publishing course videos

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.

### News channels publishing breaking story videos at speed

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.

### SaaS tools producing demo videos

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.

## Output

- **Dimensions:** 1280x720
- **Colour space:** sRGB
- **Transparency:** Not supported
- **Typical file size:** 80 KB to 350 KB
- **Platform specification:** [YouTube thumbnail dimensions and constraints](https://support.google.com/youtube/answer/72431)

## Common mistakes

### Contrast too low against the player overlay

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.

### Important content placed where the duration badge sits

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.

### Files over 2 MB rejected by YouTube uploader

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.

## Questions

### 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.

## Preview

![Youtube Thumbnail Generator API example render](https://i.html2img.com/image-1777560094062-843480.png)

## Related templates

- [instagram-square-post](https://html2img.com/templates/instagram-square-post/)
- [open-graph-image](https://html2img.com/templates/open-graph-image/)
- [twitter-post](https://html2img.com/templates/twitter-post/)

## See also

- [Every template](https://html2img.com/templates/)
- [Templates API reference](https://html2img.com/docs/templates/)
- [OpenAPI specification](https://html2img.com/openapi.json)