YouTube thumbnails from a template: size, API and bulk

To make YouTube thumbnails from a template, design the layout once — face, big title, a highlighted word, the channel badge — then send each video's text and images to the API. Shareglint renders the thumbnail in real Chrome and returns a JPEG or PNG at 16:9, the shape YouTube asks for, in about a second; a whole series renders from one spreadsheet. Four thumbnail templates are built in (video-thumbnail, thumbnail-face, thumbnail-tutorial, thumbnail-gaming), or you write your own HTML and CSS.

Templates do not replace a designer's one-off hero thumbnail. They pay off when a channel publishes a lot in one recognisable style: episodes of a podcast, lessons of a course, match highlights, weekly news recaps, or the same video localised into five languages.

What YouTube asks for

YouTube's help page for custom thumbnails (YouTube Help, read 2026-11-04):

Custom thumbnails need a verified account. How the presets map:

• "size": "youtube" is 1280×720. Raster files come out at twice the template size, so the file is 2560×1440 — 16:9, four times the minimum width. For the full 3840×2160, save your own template at 1920×1080.
• "size": "story" (1080×1920) gives 2160×3840 for Shorts.
• "size": "square" (1080×1080) gives a 2160×2160 podcast cover.

Every built-in template lays itself out in every preset (og 1200×630, square 1080×1080, portrait 1080×1350, story 1080×1920, pinterest 1000×1500, youtube 1280×720), so one design covers the video, the Short and the community post. Keep the file under 2 MB if your team uploads from phones: JPEG ("format": "jpeg", quality 85 by default) of a photo-heavy thumbnail usually is; check the size of the PNG version before relying on it.

One thumbnail per video

curl -X POST "https://shareglint.com/v1/images?wait=true" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "template": "thumbnail-tutorial",
    "size": "youtube",
    "format": "jpeg",
    "modifications": {
      "title": "Deploy Laravel to a VPS in 10 minutes",
      "tool_name": "Laravel",
      "step_label": "Part 3",
      "level": "Beginner",
      "highlight": "10 minutes",
      "channel": "@shipfast",
      "tool_logo": "https://example.com/laravel.png",
      "screenshot": "https://example.com/terminal.png"
    }
  }'

The response holds the file's url. Images (tool_logo, screenshot, a guest's photo) are fetched from public URLs when the thumbnail renders; long titles shrink to fit their box instead of running off the image. The same values again return the same file for free, so re-running your publishing script costs nothing.

Upload it with the YouTube API

The API makes the image; uploading it is one more call on your side. The YouTube Data API's thumbnails.set takes image/jpeg or image/png up to 50 MB, needs OAuth with a YouTube scope such as youtube.upload, and costs about 50 units of your YouTube quota per call. A Node sketch with the official googleapis client:

import { Readable } from 'node:stream';
import { google } from 'googleapis';

const youtube = google.youtube({ version: 'v3', auth: oauthClient });

const image = await fetch(thumbnailUrl);              // the url from the render
await youtube.thumbnails.set({
  videoId: 'dQw4w9WgXcQ',
  media: { mimeType: 'image/jpeg', body: Readable.fromWeb(image.body) },
});

Run it after the video upload in the same job, and the video goes live with its thumbnail in place.

A whole series from a spreadsheet

For a back catalogue — 80 podcast episodes, a 30-lesson course — put one row per video in a sheet: title, highlight, channel, photo (a URL), a filename such as ep-042.jpg, and an id with the YouTube video id. Then:

curl -X POST "https://shareglint.com/v1/batches" \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "template": "thumbnail-face", "format": "jpeg", "sizes": ["youtube"],
        "csv_url": "https://docs.google.com/spreadsheets/d/…/edit?usp=sharing" }'

GET /v1/batches/{id} reports progress and, when done, each row's URL (with its id, ready for thumbnails.set) and one ZIP. Rows per batch by plan: Free 50, Starter 500, Pro 1,000, Scale 2,000, Business 5,000. Change one title and run the batch again, and only that row renders anew. The dashboard's Bulk page does the same from an uploaded CSV, with a free preview of the first rows.

Testing variants

YouTube's own Test & compare tries up to three thumbnails against each other on a published video, in YouTube Studio on a computer, and recommends at least 1280×720 for every variant. A template makes the variants cheap: the same video with the title as a question or a statement, a different highlight word, theme light or dark, a different accent colour. Each variant is one render; render three, upload them to the test, keep the winner. We do not run the test or read your analytics — YouTube Studio does.

Design notes that matter at thumbnail size

• Few words, large type. A thumbnail is often seen at a fraction of its size in search results and on phones; four to six words in heavy type read, a sentence does not. The highlight field colours one or two words.
• Faces and contrast. Templates with a photo or face_photo field cut a portrait into the layout; use a photo with the subject well lit and the background simple.
• Keep the bottom right clear. YouTube overlays the video length there.
• Your own fonts? Templates use the font families installed on our renderer (GET /v1/fonts); you cannot upload a font file. The list is short — Roboto, Open Sans, Ubuntu and a few more — so if your channel's look depends on a particular display face, check the list first.

Cost

One render per thumbnail and size. A weekly channel with one thumbnail and two variants uses about 12 renders a month; a 300-video back catalogue in one size is 300 renders. The Free plan's 100 renders a month carry a watermark — fine for trying templates, not for publishing. Starter is $9 a month for 2,000 renders with no watermark (pricing).

What it does not do

• It does not upload to YouTube or read YouTube Analytics; your script or YouTube Studio does that.
• It does not pick a frame from your video. Use a still you export, or a photo, in an image field.
• No AI-generated faces or scenes: the template lays out the images you provide.
• Animated output (GIF/MP4 up to 5 s) exists, but YouTube thumbnails are still images, so use JPEG or PNG.