Build Link Previews with a Screenshot API

When someone shares a link on social media, in a chat app, or inside a CMS dashboard, a visual preview makes the difference between a click and a scroll-past. Building those previews manually is impractical at scale. The Apixies Screenshot API lets you generate link preview images automatically -- send a URL, get back a thumbnail-ready screenshot in PNG or JPEG format.

Why Screenshot-Based Link Previews?

Most link preview systems rely on Open Graph (OG) meta tags embedded in the target page. That approach has real limitations:

• Many pages lack OG images entirely. Small blogs, documentation sites, and internal tools rarely set og:image.
• OG images are inconsistent. Some are cropped logos, others are oversized banners. Sizes and aspect ratios vary wildly.
• You cannot control the output. The site owner decides what the preview looks like, not you.

A screenshot-based preview solves all three problems. You capture exactly what the page looks like in a real browser, crop or resize as needed, and serve a consistent image every time. Your users see the actual page content rather than a generic placeholder.

How It Works

The Apixies Screenshot API renders any URL in a headless Chromium browser and returns the result as a binary image. For link previews, you typically want a viewport-sized screenshot (not full-page) at a specific width:

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://apixies.io/api/v1/screenshot?url=https://example.com&width=1200&height=630&format=jpeg" \
  -o preview.jpg

A 1200x630 viewport matches the recommended OG image dimensions used by Facebook, LinkedIn, and most social platforms. By requesting JPEG format, you keep file sizes small -- typically 80-150 KB per preview, which loads quickly on any connection.

See the Screenshot API documentation for the complete parameter reference.

Generating Previews in Your Application

Node.js Example

This function takes a URL, captures a preview image, and returns it as a Buffer you can store or serve directly:

async function generateLinkPreview(targetUrl) {
  const params = new URLSearchParams({
    url: targetUrl,
    width: "1200",
    height: "630",
    format: "jpeg",
  });

  const response = await fetch(
    `https://apixies.io/api/v1/screenshot?${params}`,
    { headers: { "X-API-Key": process.env.APIXIES_KEY } }
  );

  if (!response.ok) {
    throw new Error(`Preview generation failed: ${response.status}`);
  }

  return Buffer.from(await response.arrayBuffer());
}

// Usage: save to disk or upload to S3/R2
const fs = require("fs");
const preview = await generateLinkPreview("https://news.ycombinator.com");
fs.writeFileSync("hn-preview.jpg", preview);

Python Example

import requests
import os

def generate_link_preview(target_url: str, output_path: str):
    response = requests.get(
        "https://apixies.io/api/v1/screenshot",
        params={
            "url": target_url,
            "width": 1200,
            "height": 630,
            "format": "jpeg",
        },
        headers={"X-API-Key": os.environ["APIXIES_KEY"]},
    )
    response.raise_for_status()

    with open(output_path, "wb") as f:
        f.write(response.content)

    return output_path

generate_link_preview("https://github.com", "github-preview.jpg")

PHP Example

function generateLinkPreview(string $url, string $outputPath): void
{
    $query = http_build_query([
        'url'    => $url,
        'width'  => 1200,
        'height' => 630,
        'format' => 'jpeg',
    ]);

    $ch = curl_init("https://apixies.io/api/v1/screenshot?{$query}");
    curl_setopt($ch, CURLOPT_HTTPHEADER, ['X-API-Key: ' . getenv('APIXIES_KEY')]);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

    $image = curl_exec($ch);
    $status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
    curl_close($ch);

    if ($status === 200) {
        file_put_contents($outputPath, $image);
    }
}

generateLinkPreview('https://laravel.com', 'laravel-preview.jpg');

Practical Architecture: When and Where to Generate Previews

Generating a screenshot on every page load is wasteful. A better approach is to capture the preview once and cache it. Here is a common pattern:

1. Capture on First Request

When a user submits a URL (in a CMS, bookmark tool, or social feed), call the Screenshot API immediately or add the job to a background queue. Store the resulting image in your object storage (S3, R2, GCS, or local disk).

2. Serve from Cache

On subsequent requests, serve the cached image directly. Set a long Cache-Control header since the preview rarely needs to change in real time.

3. Refresh on a Schedule

For pages that update frequently (news sites, dashboards), set up a daily or weekly cron job to re-capture previews. The free tier gives you 75 requests/day with a free account -- enough to refresh a library of bookmarks or a modest link directory without hitting limits.

4. Fallback Gracefully

If the Screenshot API is temporarily unreachable or returns an error, display a generic placeholder image rather than breaking your UI. Log the failure and retry on the next cycle.

Choosing the Right Dimensions

The viewport size you choose depends on where the preview will appear:

You can generate multiple sizes from the same URL if needed. One call at 1200x630 for social sharing and another at 640x400 for your internal dashboard -- each is a single GET request.

Using JPEG for Smaller Previews

For link preview images, JPEG is almost always the better format choice. Screenshots of websites tend to contain photographic elements, gradients, and complex color palettes -- exactly the type of content JPEG compresses efficiently.

curl -H "X-API-Key: YOUR_API_KEY" \
  "https://apixies.io/api/v1/screenshot?url=https://example.com&format=jpeg&width=1200&height=630" \
  -o preview.jpg

A typical 1200x630 JPEG preview weighs between 80 and 200 KB, while the same image in PNG can easily be 500 KB or more. If you are serving hundreds of previews on a single page -- think link aggregators or bookmark managers -- this difference adds up fast.

Serving Previews as OG Images

Once you have generated and stored a preview image, reference it in your page's <head> so social platforms pick it up automatically:

<meta property="og:image" content="https://yoursite.com/previews/abc123.jpg" />
<meta property="og:image:width" content="1200" />
<meta property="og:image:height" content="630" />
<meta name="twitter:card" content="summary_large_image" />
<meta name="twitter:image" content="https://yoursite.com/previews/abc123.jpg" />

This approach gives you full control over the preview image for every link on your site, regardless of whether the target page has its own OG tags.

Real-World Use Cases

• Bookmark managers -- Show a visual thumbnail for every saved link so users can scan their library visually instead of reading titles.
• Content management systems -- Auto-generate preview cards when editors paste a URL into a rich text field.
• Social aggregators -- Display consistent, up-to-date previews of shared links in a feed, even when the original site lacks OG images.
• Internal dashboards -- Embed live-ish previews of competitor pages, partner sites, or monitoring targets without iframes.
• SEO tools -- Show clients what their pages look like in search results or social shares.

Next Steps

The free tier at 75 requests/day with a free account is enough to build and test a full link preview system. For production workloads with higher volume, paid plans scale up from there.

• Screenshot API documentation -- full parameter reference, error codes, and rate limit details.
• Website screenshot tutorial -- a broader introduction to the Screenshot API.
• Full-page screenshots -- capture entire scrollable pages when viewport-only is not enough.
• All guides -- explore every available tutorial.

Get your free API key and start generating link previews today.