How to Add a ScreenshotMachine Preview Image to a Website Link Card

To show a ScreenshotMachine screenshot in a shared website link card, generate the screenshot image URL and set it as the target page’s og:image metadata in the HTML <head>. An <img> element in the page body displays an image to visitors; it does not by itself tell Open Graph consumers which image to use for a link preview.

1. Generate the ScreenshotMachine image URL

Choose the exact page URL that people will share, then build a ScreenshotMachine API URL with your customer key and that target URL. ScreenshotMachine documents HTTP GET requests with key and url parameters. Encode the target URL as a query parameter so its own query string and reserved characters are preserved.

https://api.screenshotmachine.com/?key=YOUR_CUSTOMER_KEY&url=https%3A%2F%2Fexample.com%2Fpage&dimension=1200x630&format=png

Replace the key and target with your values. The example dimensions are a configurable choice, not a universal social-platform requirement. The API documentation lists 120x90 as its default dimension, accepts dimensions in widthxheight form, and documents widths from 100 through 1920 and heights from 100 through 9999; full can be used for full-page height. Documented image formats are jpg, png, and gif. See ScreenshotMachine’s API documentation for the current parameters and account details.

Other documented options include device, cacheLimit, delay, and zoom. Use the vendor documentation for their accepted values. Add options only when you need them; the generated URL must resolve to an image that the metadata consumer can fetch.

2. Put the screenshot URL in Open Graph metadata

Add the tags to the HTML head of the page whose link will be shared. Set og:url to the page URL and og:image to the ScreenshotMachine image URL.

<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Example page title</title>
  <meta property="og:title" content="Example page title">
  <meta property="og:type" content="website">
  <meta property="og:url" content="https://example.com/page">
  <meta property="og:image" content="https://api.screenshotmachine.com/?key=YOUR_CUSTOMER_KEY&amp;url=https%3A%2F%2Fexample.com%2Fpage&amp;dimension=1200x630&amp;format=png">
  <meta property="og:description" content="A short description of this page.">
  <meta property="og:image:alt" content="Screenshot of the example page">
</head>
<body>
  <h1>Example page</h1>
</body>
</html>

In HTML source, query-string ampersands in an attribute are written as &. A template engine may handle this escaping for you. The Open Graph Protocol defines og:title, og:type, og:image, and og:url as the basic properties; description and image details are optional. Its og:image:alt value should describe the image rather than serve as a caption. See the Open Graph Protocol specification.

3. Keep credentials out of public source

A raw customer key in a publicly served og:image URL is visible to anyone who views the page source. ScreenshotMachine documents a hash safeguard calculated from the URL and secret phrase, and recommends it for calls made directly from public HTML. Do not publish the secret phrase. Follow the vendor’s current instructions for generating and using the hash. Another option is to generate or proxy the image URL on your server, keeping credentials server-side; this is an implementation choice, and the proxy must return an image to the preview crawler.

4. Verify the rendered page and image

Publish the page, then inspect its rendered HTML source or response.
Confirm the metadata appears in the document head, not only in client-rendered content that is absent from the initial HTML.
Check that og:url is the canonical URL of the page being shared and that og:image contains the intended screenshot URL.
Open the image URL directly and confirm it returns the expected image, rather than an error page or a redirect requiring an interactive login.
Use the destination service’s preview or debugger if one is available. Preview services may cache metadata, and their refresh behavior differs; the sources here do not establish current platform-specific refresh steps.

For a CMS or framework, set the page’s Open Graph image field or metadata template, then inspect the resulting HTML. That is an implementation inference from the protocol’s requirement for metadata in the page head.

5. Handle common problems

Symptom	Likely cause	What to check
The shared card shows the page’s old image or no image	The `og:image` tag is missing, points elsewhere, or the preview service has cached an earlier result.	Inspect the published head and use the destination’s available preview debugger. The exact cache refresh process depends on the service.
The screenshot URL displays an error or HTML instead of an image	The key, target URL, or query encoding is invalid, or the request did not produce an image.	Open the URL directly, verify the required parameters, and percent-encode the target URL.
The wrong page appears in the screenshot	The API’s `url` parameter names a different page than the shared page.	Set it to the intended page URL, including the correct path and relevant query parameters.
The capture is too small or cuts off content	The default dimensions or selected dimensions do not fit the intended card or page.	Choose a suitable documented `dimension`; use `full` height when a full-page image is appropriate. No single size is established here as mandatory across platforms.
The account key is exposed in page source	A raw key was embedded in the public image URL.	Use ScreenshotMachine’s documented hash safeguard for public HTML, or serve the image through a server-side integration that keeps the key private.
The image tag exists but the link preview ignores it	A body `<img>` is not Open Graph metadata, or the tags are absent from the HTML the crawler receives.	Set `og:image` in the head and verify the server-rendered response.

6. Reliability, performance, and cost considerations

The link preview depends on two fetches: the preview service must read the target page’s metadata, and it must be able to retrieve the screenshot image URL. Keep the image URL publicly fetchable by the relevant crawler, and avoid relying on browser-only rendering for the metadata. ScreenshotMachine documents a cacheLimit option; choose cache behavior according to how often the target changes and consult its documentation for exact semantics.

ScreenshotMachine’s API documentation referenced here establishes the request parameters but not a current complete price schedule, latency benchmark, or service-level guarantee. Check the vendor’s current account and pricing information before estimating costs or relying on a particular response time.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its one-call API returns an image or PDF; the following requests save a screenshot of the target page. See the ScreenshotNeo API documentation for options and parameter details.

curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webp

import requests
r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"}, timeout=90)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

Cookie banners, newsletter popups, and chat widgets are removed before capture. Bot checks, blank pages, timeouts, and failed loads are not billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF-capture tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000. Every feature is on every plan. To use ScreenshotNeo, sign up for the free plan.

FAQ

Does adding a screenshot with an HTML image tag create a link-card preview?

No. The image must be referenced by the page’s og:image metadata for Open Graph consumers.

Does `og:image` need to be on the page being shared?

Yes. Put the metadata in the head of the target page, and use that page’s canonical URL as og:url.

Which image dimensions should I choose?

Choose dimensions suited to the destination and the screenshot composition. The sources used here do not establish one universal size for every sharing platform.

Can I use ScreenshotMachine directly from a public page?

The vendor documents a hash safeguard for public HTML calls. Follow its instructions and never expose the secret phrase.