Let your users pick and crop the perfect thumbnail

What the thumbnail picker does

<video-piper-thumbnail> embeds the same thumbnail picker that the Video Piper app uses. Your users start from one of the video's frames, any moment of it (they play or scrub the video and press Use this frame), or their own image. Then they crop it: drag the box to move it, drag its corners to resize it, and lock it to the video's shape, 16:9, square or 4:5, or leave it free, with a live preview of the result.

Pressing Save makes it the video's poster everywhere: posterUrl in status and listings, webhooks, <video-piper> and the embed page. Cropping happens in the browser, so saving is instant, and big photos are resized for you.

The thumbnail token model

Like the recorder and the editor, the picker never sees your API key. Your server makes a thumbnail token for the one video the current user may change:

// 1. Your server (Node.js): an endpoint that makes a token (POST /thumbnail-tokens with your API key)
app.post("/api/thumbnail-token", async (req, res) => {
  const videoId = req.query.video;
  if (!(await mayChangeThumbnail(req.user.id, videoId))) return res.status(403).end();   // your own rule
  const r = await fetch(`${API}/thumbnail-tokens`, { method: "POST",
    headers: { Authorization: `Bearer ${API_KEY}`, "Content-Type": "application/json" },
    body: JSON.stringify({ videoId, expiresIn: 900 }) });
  res.status(r.status).json(await r.json());   // { token: "vpt_…", expiresAt, videoId }
});

<!-- 2. Your page: the picker asks token-url for a token when it loads -->
<script src="https://videopiper.com/thumbnail/thumbnail.js"></script>
<video-piper-thumbnail token-url="/api/thumbnail-token?video=VIDEO_ID"></video-piper-thumbnail>
<script>
  document.querySelector("video-piper-thumbnail")
    .addEventListener("vp-thumbnail-saved", (e) => console.log("new poster", e.detail.posterUrl));
</script>

Both come from the documentation, which also has an ASP.NET Core endpoint. The token body takes videoId (one of your finished videos) and expiresIn (60 to 86400 seconds, default 900).

What a token can and can't do

Or build your own picker

The same choices are plain API calls. GET /videos/{id}/thumbnails lists the frames, the current choice and the video's length. POST /videos/{id}/thumbnail takes one of:

{"candidate": 2}                                   // one of the frames
{"image": "<base64>", "contentType": "image/png"}  // your own JPEG or PNG, up to 2 MB
{"time": 42.5}                                     // any moment of the video
{"time": 42.5, "crop": {"x": 0.21875, "y": 0, "w": 0.5625, "h": 1}}   // ...cropped to the middle square

A frame or image without a crop applies at once. A moment or a crop answers 202 and is made by a short job, usually within a minute; the list shows it as processing, then ready.

Attributes, events and styling

• Attributes: token-url (recommended; the picker POSTs to it when it loads, and asks again once at Save if the token expired), or token with video-id, and title for a line under the heading.
• Events (they bubble): vp-thumbnail-ready, vp-thumbnail-saved and vp-thumbnail-error, with a message fit to show.
• Theme: --vp-bg, --vp-panel, --vp-text, --vp-muted, --vp-line, --vp-accent, --vp-accent-soft and --vp-bad, for example video-piper-thumbnail { --vp-accent: #e11d74; }.
• Size: about 75 KB compressed, so load it only where it is used.

Your account page has these snippets filled in with your addresses, and a Try the thumbnail picker button that makes a 15-minute token for your latest finished video.

Which plans include thumbnail choices

Choosing and cropping thumbnails, the picker component and its thumbnail tokens work on every plan, at no extra cost.

Usage beyond a paid plan is billed at $0.09 per processing minute, $0.15 per GB-month of storage and $0.55 per GB of delivery. Full details are on the pricing page.

In the documentation

• The video-piper-thumbnail web component
• Thumbnail tokens
• Thumbnails (the API)
• Errors

Frequently asked questions