Skip to content
Vumbnail

How it works

A thumbnail request travels through three layers: a cheap edge Snippet, the main thumbnail Worker, and the upstream video provider. Most requests never get past the first two.

The end-to-end flow

Section titled “The end-to-end flow”

  1. A browser requests an image. Somewhere a page contains <img src="https://vumbnail.com/637615910.jpg">. The browser fetches that URL.

  2. The edge Snippet looks first. A tiny Cloudflare Snippet runs ahead of the Worker. For a small, hand-maintained set of hot videos requested by watermark-eligible referrers, it redirects straight to the pre-rendered watermarked image in public storage — the Worker never runs, which keeps cost down. Paying domains and IPs are excluded so they always reach the Worker for a clean image. Everything else passes through. See Edge watermark router.

  3. The Worker resolves the request. The thumbnail Worker parses the URL into a provider, a video ID, an optional password, and a size. It then decides one thing: should this viewer get a clean image or a watermarked one? That decision is the whole business model and is covered in Freemium watermarking and Paid access & entitlements.

  4. Caching is checked, cheapest first. The Worker looks in the Cloudflare edge cache, then in an R2 bucket for the already-resolved clean and watermarked variants. A warm thumbnail is returned immediately. See Caching & delivery.

  5. On a miss, the source is fetched. If nothing is cached, the Worker resolves the real poster image from the provider (Vimeo or YouTube, directly or via a relay), stores the clean variant in R2, applies the watermark if needed, populates the caches, and returns the image.

  6. Failure degrades gracefully. Unknown IDs, blocked or deleted videos, and password-protected videos resolve to small shared fallback graphics (error.jpg / locked.jpg) instead of an error, and the negative result is cached so the failing upstream isn’t hammered.

The money path

Section titled “The money path”

Vumbnail never returns “quota exceeded.” Instead:

  • A free site under its monthly allowance gets clean images.
  • A high-volume free site (over the threshold, matched by referrer or other signals) gets a watermarked image — a visible nudge to subscribe.
  • A paying site is matched against an allow-list of domains, IPs, API keys, and user-agents, and is served clean images. The allow-list is kept current automatically from Stripe subscription webhooks.

The operator watches all of this on the dashboard and reaches out to over-threshold domains with the outreach toolkit.

Where it runs

Section titled “Where it runs”

Everything is Cloudflare-native: Workers for compute, R2 for the persistent thumbnail store, KV for the live entitlement allow-list, D1 for the billing record of truth, and a Snippet at the very edge for cost control. The full map is in Deployment topology.