Website Thumbnail API for Developers

What is a website thumbnail API?

A website thumbnail API accepts a URL and returns a rendered screenshot of the page — typically scaled to a small preview image. It uses headless Chromium to render exactly as a browser would: JavaScript executes, CSS applies, fonts load, layout completes. The result is an accurate visual representation of the page at the moment of capture.

Website thumbnails are used for link preview cards in dashboards, bookmark managers, browser history UIs, website monitoring tools, social sharing metadata, and directory listings that display visual previews alongside text descriptions.

Generate a thumbnail in one request

curl -X POST https://your-openkova-instance/api/convert/url \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "jpeg",
    "viewport": {"width": 1280, "height": 800}
  }' \
  --output thumbnail.jpg

For a true thumbnail at a fixed preview size, pipe the output through an image resizing library:

// generate-thumbnail.ts
import sharp from 'sharp';

async function generateThumbnail(url: string, width = 280, height = 180) {
  const res = await fetch('https://your-openkova-instance/api/convert/url', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      url,
      format: 'jpeg',
      viewport: { width: 1280, height: 800 },
    }),
  });

  const buffer = Buffer.from(await res.arrayBuffer());

  return sharp(buffer)
    .resize(width, height, { fit: 'cover', position: 'top' })
    .jpeg({ quality: 80 })
    .toBuffer();
}

Common use cases

Link preview cards

Generate thumbnail previews for bookmarks, saved links, and browser history UIs. Capture at 1280×800 (full desktop viewport) and scale down to 280×180 or 320×200 for display. Cache the thumbnail against the URL with a TTL of 24–72 hours.

Website monitoring

Capture thumbnails of your pages on a schedule and diff against a baseline to detect visual changes — defacements, layout breakage, unexpected downtime pages. Combine withpixelmatch for automated alerting.

Directory and listing pages

Display visual previews alongside text listings in website directories, app showcases, and portfolio galleries. Generate thumbnails at submission time and cache them — no re-render required until the site changes.

Social sharing metadata previews

Preview how any URL will look when shared on social platforms. Screenshot the page at 1200×630 to simulate the Open Graph image viewport, or at mobile dimensions to show the mobile rendering.

Comparison: website thumbnail API options

Thumbnail generation in bulk

For batch thumbnail generation — screenshotting a list of URLs on a schedule — use the URL crawl endpoint with depth 0, or loop over URLs using @openkova/cli:

# Generate thumbnails for a list of URLs using the CLI
while IFS= read -r url; do
  slug=$(echo "$url" | sed 's|https?://||;s|/|-|g')
  kova screenshot "$url" --output "thumbnails/$slug.jpg" --format jpeg
done < urls.txt

Caching thumbnails

Website thumbnails are expensive to generate (1–3 seconds per page with a full Chromium render) and change infrequently. Cache aggressively:

• On-demand with TTL — generate on first request, store in S3 or on-disk, serve cached version until TTL expires (24–72h)
• Scheduled refresh — regenerate thumbnails on a cron schedule (daily or weekly) and invalidate the cache
• On-change — regenerate when a webhook fires (deployment, sitemap update), keeping thumbnails fresh without wasted renders

Deploy Openkova

docker run -p 3000:3000 \
  -e CHROMIUM_PATH=/usr/bin/chromium \
  -e OPENKOVA_STORAGE_PATH=/data \
  -v $(pwd)/data:/data \
  ghcr.io/scnix-git/openkova:latest

For cloud deployment, see the guides for Railway, Fly.io, and Render.

Frequently asked questions

What is a website thumbnail API?

A website thumbnail API accepts a URL and returns a rendered screenshot — typically scaled to a small preview size. It uses headless Chromium to render pages as a browser would, including JavaScript and CSS, then returns the image bytes.

How do I generate website thumbnails for free?

Deploy Openkova with Docker and call POST /api/convert/url with your target URL. No API key, no rate limits, no per-thumbnail fee.

Can I thumbnail private or internal URLs?

Yes — self-hosted Openkova runs Chromium on your own server, so it can reach localhost, internal networks, VPN-protected services, and staging environments. SaaS thumbnail APIs run on external servers and cannot access private URLs.

What is the best free website thumbnail API?

Openkova is the best free option for developers who can self-host — MIT-licensed, no usage limits, accurate Chromium rendering. Microlink offers 1,500 free requests per month for zero-setup managed access.

How do I thumbnail a page at a specific size?

Set the viewport parameter to control the captured browser window size, then use a library like sharp to resize the output to your display dimensions. For link preview cards, capture at 1280×800 and resize to 280×180 withfit: cover.