Skip to content
Screenshot API · Use case

Generate dynamic Open Graph images from a screenshot of the page

A dynamic Open Graph image does not need a template engine when the page already looks the way you want it shared. With the embed option the Screenshot API URL behaves like an image file, so og:image can point straight at a live capture. Blogs, docs sites, changelogs, directories and user-generated pages get a unique social card per URL without designing a single one.

Start with the Screenshot API
A blog post captured at the 1200 by 630 Open Graph size
Generated live by the API call below: a 1200×630 viewport, the common size for social cards.
The problem

Static og:image files go stale and custom renderers are work

One default banner makes every share of your site look the same, and links with a generic preview get scrolled past. A hand-made image per page fixes that for ten pages, not for ten thousand, and it is out of date the day someone edits the headline.

The usual answer is an OG image service: HTML templates, bundled fonts, a renderer on a serverless function and a cache in front of it. That is a second front end to design, deploy and keep in sync with the first one. Meanwhile the page itself is already rendered, styled and current.

The embed parameter returns one field of the response as the body, with the headers of the original resource. Set it to screenshot.url and the API URL is the PNG. Drop that URL into og:image and twitter:image and crawlers receive a capture of the page, rendered on the first request and served from the cache after that. The delivery and embedding guide shows the same URL in HTML, CSS and Markdown.

How it works

How to generate an og:image from a screenshot URL

Set the viewport to the social card size, ask for the image directly with embed, and reference the resulting URL in your meta tags. The default cache keeps the card for 24 hours.

1 · Build the image URL
curl 'https://api.microlink.io/?url=https%3A%2F%2Fyour-site.com%2Fblog%2Fpost&screenshot=true&meta=false&embed=screenshot.url&viewport.width=1200&viewport.height=630'

embed=screenshot.url makes the response the PNG itself instead of JSON, captured at 1200×630. meta=false skips metadata detection, so the first render is faster.

2 · Reference it in the page head
<meta property="og:image" content="https://api.microlink.io/?url=https%3A%2F%2Fyour-site.com%2Fblog%2Fpost&screenshot=true&meta=false&embed=screenshot.url&viewport.width=1200&viewport.height=630" />
<meta name="twitter:image" content="https://api.microlink.io/?url=https%3A%2F%2Fyour-site.com%2Fblog%2Fpost&screenshot=true&meta=false&embed=screenshot.url&viewport.width=1200&viewport.height=630" />

Crawlers fetch the API URL like any image. URL-encode the target, and check the result with the sharing debugger before you ship.

3 · Add a frame and a longer cache
import createClient from 'microlink.io'

const microlink = createClient({
  apiKey: process.env.MICROLINK_API_KEY
})

const { url } = await microlink.screenshot('https://your-site.com/blog/post', {
  viewport: { width: 1200, height: 630 },
  overlay: { browser: 'dark', background: '#0473e4' },
  ttl: '7d',
  staleTtl: 0
})

overlay composes a browser frame over a background, as in the browser frame recipe. ttl and staleTtl need a Pro key, so run this from your backend or send the same options through your own proxy.

Parameters used
  • embed Returns one field of the response as the body. screenshot.url returns the image.
  • viewport 1200×630 is the common social card size. Set deviceScaleFactor to 2 for a sharper image.
  • screenshot.overlay Browser window frame, light or dark, over a color, gradient or image background.
  • ttl Cache lifetime from 1 minute to 31 days. Defaults to 24 hours. Pro plans.
  • staleTtl Serves the cached card instantly and refreshes it in the background. Pro plans.

Keep API keys out of public og:image URLs. The free endpoint needs no key and allows 25 requests per day, which suits a small site because cache hits do not count. For production, put the request behind your own domain as described in the authentication docs.

Why it works

Why a live screenshot works as a social preview image

The page is the most accurate preview of itself, and a social preview image API that already caches and serves images at the edge removes the rest of the stack.

01 · Always current
The card updates when the page does.
Change a headline or a hero and the next cache refresh updates the preview. There is no redeploy, no regenerate step and no stale banner from last year. With staleTtl the cached card is served instantly while a fresh one renders in the background.

After a viral share, crawlers and unfurlers request the same URL over and over. The cache absorbs that burst, as the traffic spikes recipe explains, and with a configurable TTL those cache hits do not count against your quota.

02 · Framed on demand
overlay turns a raw capture into a designed card.
A browser frame over a brand color or a gradient reads as intentional on X, Slack and LinkedIn. It takes one option instead of a template engine, and it follows the page through every redesign.

Pick the light or dark frame to match the page theme. The background accepts hex, rgb or rgba colors, CSS gradients or an image URL.

03 · Served like an image
The URL works anywhere an image does.
Meta tags, README files, CMS fields, email templates: anything that can load an image URL can load the API URL. Embedded assets are served with a strict Content-Security-Policy and nosniff headers, so the response stays a plain image.

When not to: if the card needs text that is not on the page, such as an author or a series name, render a dedicated card and use the screenshot only as its backdrop. If the page has no og:image at all and you cannot edit it, override the metadata on the consuming side instead.

FAQ

Do social networks accept a screenshot API URL as og:image?

Yes. Crawlers request the URL and receive a PNG with an image content type, because embed mimics the headers of the original resource. Make sure the URL is absolute, URL-encoded and publicly reachable, and give the first crawl a moment to render.

What size should an Open Graph screenshot be?

Set the viewport to 1200×630 for the standard 1.91:1 card. Add deviceScaleFactor: 2 for a 2400×1260 image when you want it crisp on high-density screens, at the cost of a larger file.

How often does a dynamic Open Graph image screenshot refresh?

Every 24 hours by default, when the cached copy expires. On Pro plans ttl sets the lifetime from 1 minute to 31 days and staleTtl refreshes in the background while serving the cached card. The caching guide has the recommended production setup.

How do I keep my API key out of the og:image screenshot URL?

On the free endpoint no key is needed. On Pro, do not put the key in the URL: route the request through your own server or edge function with @microlink/proxy or @microlink/edge-proxy, and reference your own domain in og:image.
The proxy only lets an allowed list of domains consume your quota, so the key never reaches the page source.

Will the Open Graph screenshot include cookie banners or ads?

Not by default. adblock is enabled and blocks ads, trackers and third-party consent popups. For a first-party banner, add a click or a styles rule to the same URL, as in the cookie banner recipe.
Related use cases

Solve the next problem with the same API

Screenshots with a browser frame

Wrap the capture in a light or dark browser window over a color, gradient or image background.
Add a browser frame 

Screenshots under traffic spikes

Absorb bursts of screenshot traffic without a browser pool: no throttling, parallel requests and a cache whose hits are free.
Handle traffic spikes 

Screenshots in dark mode

Set prefers-color-scheme before the capture and get the dark or light theme of any page that supports it.
Capture dark mode 

PDF download links and previews

Turn the API URL into the PDF itself for one-click download links and iframe previews, with no storage pipeline.
Create PDF download links 

Fix missing or wrong og:image

Override any normalized field with a rule and chain fallbacks so link previews never render empty.
Fix a broken og:image 

Link previews at scale

Unfurl links at any volume: no throttling, background refresh and cache hits that never count against your quota.
Scale your link previews 

Ready to ship live social cards?

One URL per page, cached and framed. Start on the free endpoint and point your og:image at a real screenshot today.

Generate your first OG image