Website Thumbnail API: How to Generate Link Preview Images at Scale

Paste a link into Slack, iMessage, or a CMS field and a small preview card appears: a title, a snippet of text, and an image pulled from the page. That image is doing more work than it looks like it's doing. A missing or broken one quietly kills click-through before anyone reads a word of your copy.

If you're building a product that needs those preview images generated on demand, hand-cropping screenshots isn't a real option past a handful of URLs. You need a website thumbnail API: a service that takes a URL and hands back a rendered image you can drop into an og:image tag, a bookmarking tool, or a CMS field, without you having to run a browser yourself.

This guide covers what a website thumbnail API actually does, where link previews matter, and how to generate them programmatically with ScreenshotAPI.net.

What Is a Website Thumbnail API?

A website thumbnail API is a REST service that accepts a target URL, renders it in a real browser engine, and returns an image or a JSON object containing the image URL. Instead of installing Puppeteer or Playwright, spinning up headless Chromium instances, and maintaining that infrastructure yourself, you send one HTTP request and get a screenshot back.

The term overlaps with a few others you'll see in search results: link preview API, website preview image API, and URL-to-image API. They all describe roughly the same job, capturing a visual representation of a webpage for use somewhere else.

Under the hood, a proper thumbnail API is running the same rendering pipeline as any full screenshot service. That distinction matters because thumbnails generated from a real browser handle JavaScript-heavy pages correctly, while lightweight scrapers that just fetch raw HTML often return blank or broken previews for anything built with React, Vue, or Next.js.

Why Link Preview Images Matter

Every major platform that lets you paste a URL, Slack, Discord, WhatsApp, LinkedIn, X, iMessage, reads a page's markup looking for an og:image tag defined by the Open Graph protocol. If it finds one, it renders a rich card. If it doesn't, most platforms either fall back to a random image scraped from the page or show no image at all.

Links with custom preview images get 2 to 3 times more clicks on social platforms than links without them. That's a meaningful gap when you're talking about shared blog posts, product pages, or documentation links, all of which live or die on click-through in a crowded feed.

The practical challenge is scale. A static, hand-designed og:image works fine for a homepage. It falls apart the moment you have thousands of blog posts, user profiles, or product listings, each of which needs its own accurate preview. That's the specific problem a thumbnail API solves: generating a correct, current preview image automatically at publish time instead of manually.

Common Use Cases

Dynamic OG images for blogs and product pages. Generate a fresh og:image for every article or listing the moment it's published, without a designer touching Figma.

Bookmarking and read-it-later apps. Show users a visual snapshot of the pages they've saved instead of a bare URL string.

CMS and page builders. Auto-populate a thumbnail field when a user pastes a URL into a form, similar to how Notion or Slack render link cards.

Directory and marketplace listings. Show a live preview of a linked business, portfolio, or listing page instead of relying on the vendor to upload one.

Internal tools. Dashboards that link out to external resources (competitor pages, client sites, documentation) benefit from a quick visual thumbnail instead of a plain text link.

How Website Thumbnail APIs Work

At a technical level, most thumbnail APIs follow the same sequence:

1. You send a GET or POST request with the target URL and your API key.
2. The service launches a headless Chromium instance and navigates to that URL.
3. It waits for the page to finish rendering, JavaScript execution, lazy-loaded images, network requests.
4. It captures either the visible viewport or the full scrollable page.
5. It returns the image directly, or a JSON payload containing a hosted URL to the image.

The details that separate a reliable service from a fragile one are mostly in step 3: how well it handles single-page apps, ad and cookie-banner blocking, and timing controls for animation-heavy pages.

How to Generate Website Preview Images Using ScreenshotAPI.net

ScreenshotAPI.net exposes a single endpoint, https://shot.screenshotapi.net/v3/screenshot, that handles both full screenshots and thumbnail-style captures depending on the parameters you pass. Authentication is a token query parameter tied to your account, available from the dashboard after signup.

For a link-preview use case specifically, the parameters that matter most are:

A 1200×630 pixel image at a 1.91:1 ratio is the size most platforms, including Facebook and LinkedIn, expect for a link-preview card, so it's a sensible default when generating thumbnails specifically for og:image use, per the Open Graph protocol.

Basic thumbnail request (cURL)

curl --location 'https://shot.screenshotapi.net/v3/screenshot?token=YOUR_API_KEY&url=https://example.com&output=json&file_type=png&width=1200&height=630&full_page=false&block_ads=true&no_cookie_banners=true'

This returns a JSON object with the hosted screenshot URL you can store or pass directly into an og:image tag.

Node.js

const fetch = require("node-fetch");

async function generateThumbnail(targetUrl) {
  const token = "YOUR_API_KEY";
  const encodedUrl = encodeURIComponent(targetUrl);

  const query =
    `https://shot.screenshotapi.net/v3/screenshot` +
    `?token=${token}` +
    `&url=${encodedUrl}` +
    `&output=json` +
    `&file_type=png` +
    `&thumbnail_width=1200` +
    `&full_page=false` +
    `&block_ads=true&no_cookie_banners=true`;

  const response = await fetch(query);
  const result = await response.json();
  return result.screenshot; // hosted image URL
}

generateThumbnail("https://example.com").then(console.log);

Python

import urllib.parse
import requests

token = "YOUR_API_KEY"
target_url = urllib.parse.quote_plus("https://example.com")

query = (
    "https://shot.screenshotapi.net/v3/screenshot"
    f"?token={token}&url={target_url}&output=json&file_type=png"
    "&thumbnail_width=1200&full_page=false"
    "&block_ads=true&no_cookie_banners=true"
)

response = requests.get(query)
result = response.json()
print(result["screenshot"])

PHP

<?php
$token = 'YOUR_API_KEY';
$url = urlencode('https://example.com');

$query = "https://shot.screenshotapi.net/v3/screenshot";
$query .= "?token=$token&url=$url&output=json&file_type=png";
$query .= "&thumbnail_width=1200&full_page=false";
$query .= "&block_ads=true&no_cookie_banners=true";

$response = file_get_contents($query);
$result = json_decode($response, true);

echo $result['screenshot'];

If you'd rather test parameters visually before writing code, ScreenshotAPI's Query Builder in the Playground lets you enter a URL, toggle options, and generate the request URL for you.

Scaling Thumbnail Generation

A single API call is easy. Generating previews for thousands of URLs at once, or keeping them fresh as pages change, is where most homegrown solutions break down.

Bulk generation. For a backlog of existing content, ScreenshotAPI's bulk screenshot feature accepts a CSV or JSON list of URLs and applies the same parameters uniformly, which is faster than looping requests yourself and managing concurrency.

Caching. Previously rendered screenshots are cached, so requesting a preview for a URL and parameter combination you've already captured returns instantly and doesn't count against your quota. Only set fresh=true when the underlying page has actually changed and you need an updated preview.

Scheduled refresh. For pages that update regularly (a pricing page, a changelog, a live dashboard), the scheduled screenshot feature can re-capture a thumbnail on a cron interval so your preview cards never go stale.

Storage. By default, images are hosted on ScreenshotAPI's storage. If you want thumbnails to live in your own infrastructure, byob=true routes captures directly to your S3, Google Cloud Storage, or Wasabi bucket.

Performance Best Practices

A few practical adjustments make a real difference in output quality and cost at volume:

• Keep full_page set to false for thumbnails. You want the above-the-fold view, not the entire scrollable page; a shorter capture also renders faster.
• Use block_ads=true and no_cookie_banners=true so consent popups and ad units don't dominate the visible frame.
• Stick to 1200×630 rather than requesting oversized dimensions. Larger images cost more render time and bandwidth without improving how the thumbnail displays in a preview card.
• Rely on caching by default, and only pay the cost of a fresh render when content has actually changed.
• For JavaScript-heavy pages, pair lazy_load=true with a short delay so components finish hydrating before the capture fires, instead of getting a partially loaded thumbnail.

Website Thumbnail API vs Traditional Screenshot Solutions

Running your own headless browser fleet gives you full control, but it also means managing Chromium versions, memory leaks under load, and proxy rotation for blocked sites. For teams generating a handful of thumbnails a month, that overhead isn't worth it. For teams generating thousands, it becomes a full-time maintenance burden that a managed API removes entirely.

Conclusion

A website thumbnail API turns a manual, one-off design task into something you can run at the scale of your content. Whether you're generating og:image tags for a blog, building a bookmarking tool, or populating a directory of listings, the pattern is the same: send a URL, get back a correctly sized, ad-free image, and let caching and scheduling handle freshness. ScreenshotAPI.net's documentation covers the full parameter set if you want to go beyond the basics covered here.

Frequently Asked Questions

What size should a website thumbnail be for link previews?

1200×630 pixels at a 1.91:1 aspect ratio is the standard most platforms, including Facebook and LinkedIn, expect for Open Graph preview images.

Can a thumbnail API capture JavaScript-heavy websites correctly?

Yes, as long as it renders pages in a real browser engine rather than parsing raw HTML. ScreenshotAPI waits for scripts to execute and content to hydrate before capturing.

Is there a free way to test a website thumbnail API?

ScreenshotAPI.net offers a free trial with 100 screenshots and no credit card required, which is enough to test thumbnail generation before committing to a paid plan.

How do I keep a link preview image up to date after a page changes?

Use the fresh=true parameter to bypass the cache on demand, or set up a scheduled screenshot job to re-capture the thumbnail automatically on a cron interval.