How to use ScreenshotMachine CLI to generate Open Graph images

The title combines two different tools. ScreenshotMachine documents a hosted website screenshot API and a Bash/curl example; its documentation does not identify a dedicated product called “ScreenshotMachine CLI.” The separate og-screenshots project describes itself as a local CLI for generating Open Graph images.

Use ScreenshotMachine from a terminal by sending an HTTP GET request to its API with curl. Use og-screenshots if you want a local command-line tool that can discover pages from a sitemap or RSS feed and capture them using your local Chrome installation. Both workflows are below.

Use ScreenshotMachine from Bash

ScreenshotMachine’s documented command-line workflow is a Bash script that calls its hosted API. You need an account customer key and the page URL. The secret phrase is optional unless configured for your account; when configured, the API requires a correct hash.

1. Get your customer key from your ScreenshotMachine account. Keep it private.
2. Choose the page URL and image dimensions. The API documentation recommends percent-encoding the URL; curl’s --data-urlencode handles this.
3. Run a GET request and save the returned image bytes to a file.

#!/usr/bin/env bash
set -euo pipefail

CUSTOMER_KEY="YOUR_CUSTOMER_KEY"
PAGE_URL="https://example.com/article"
OUTPUT="output.png"

args=(
  --data-urlencode "key=${CUSTOMER_KEY}"
  --data-urlencode "url=${PAGE_URL}"
  --data-urlencode "dimension=1200x630"
  --data-urlencode "device=desktop"
  --data-urlencode "format=png"
  --data-urlencode "cacheLimit=14"
  --data-urlencode "delay=2000"
  --data-urlencode "zoom=100"
)

curl -fGs "https://api.screenshotmachine.com/" "${args[@]}" -o "${OUTPUT}"
printf 'Saved %s\n' "${OUTPUT}"

Replace the placeholder key and target URL before running. The options shown follow the API’s documented example; dimensions, device, format, cache age, delay, and zoom can be adjusted. The documented API returns an image response, which curl writes directly to the named file. The API’s documentation and parameter details are at ScreenshotMachine’s API guide.

ScreenshotMachine parameters that affect the result

Parameter	Meaning and documented constraints
key	Your account customer key. Required for the hosted request.
url	Page to capture. Required. Percent-encoding is recommended; curl encodes it with --data-urlencode.
dimension	Width-by-height, such as 1200x630. Width is documented from 100 to 1920 pixels; height from 100 to 9999. Use full for a full-page capture.
format	Documented formats are jpg, png, and gif. Choose the extension to match the requested format.
device	One of desktop, phone, or tablet.
cacheLimit	Cache age in days, from 0 through 14. Zero disables use of a cached image.
delay	Wait before capture. The API guide recommends a longer delay for long pages with images or animations.
zoom	Controls page zoom in the documented example. Choose a value that produces the framing you need.
hash	MD5 of the URL parameter value followed by your secret phrase. Use it for public HTML requests when a secret phrase is set; requests without the correct hash are ignored in that case.

For Open Graph cards, 1200×630 is a commonly used landscape target and is the size recommended by the og-screenshots README. ScreenshotMachine’s API guide allows that dimension. Check the resulting crop and legibility on the platforms where you intend to share the page.

Calling ScreenshotMachine from Python

The ScreenshotMachine Python repository demonstrates creating an API URL and retrieving the image. This runnable variant uses Python’s standard library, keeps the key as a placeholder, and writes the response bytes to disk.

from urllib.parse import urlencode
from urllib.request import urlopen

params = {
    "key": "YOUR_CUSTOMER_KEY",
    "url": "https://example.com/article",
    "dimension": "1200x630",
    "device": "desktop",
    "format": "png",
    "cacheLimit": "14",
    "delay": "2000",
    "zoom": "100",
}
request_url = "https://api.screenshotmachine.com/?" + urlencode(params)

with urlopen(request_url, timeout=90) as response:
    image = response.read()

with open("output.png", "wb") as output:
    output.write(image)

For a production script, inspect the HTTP response status and content type before treating the body as an image. Never commit a real account key to a public repository.

Public pages and request signing

A request URL containing a customer key can be visible to anyone who can inspect the page or its network requests. ScreenshotMachine documents a hash option for public HTML requests: it is the MD5 of the URL parameter value concatenated with the account secret phrase. Follow the vendor’s exact hashing instructions, and do not expose the secret phrase itself in browser code. If you need to generate signed public requests, create the hash on a server you control and return only the permitted request data.

Use the separate local CLI: og-screenshots

og-screenshots is the project in the research dossier that explicitly calls itself a CLI for Open Graph images. It runs locally and requires Node.js 16 or later, Chrome, and ImageMagick’s convert command. The README says it was tested only on macOS, marks the project beta, and warns that the process can sometimes hang. Treat operation on other platforms as unverified.

Install it globally:

npm install --global og-screenshots

Or invoke it through npx without a global install:

npx og-screenshots --url "https://example.com/article"

The default output directory is ./public/screenshots, the default extension is WebP, and the recommended image size is 1200×630. Existing images are skipped unless you pass --overwrite.

Capture pages from a sitemap or feed

The required --url input can be one page URL, a sitemap, or an RSS feed. When given a sitemap or feed, the tool can process multiple detected URLs. For example:

npx og-screenshots --url "https://example.com/sitemap.xml"

Use this for a batch run after checking that the supplied sitemap or feed contains the pages you want. To limit the amount of work, use --max-screenshots.

Local CLI options

Option	Purpose
--url	Required page URL, sitemap URL, or RSS feed URL.
--transform	Applies the project’s image transformation behavior; consult its README for accepted transform syntax.
--max-screenshots	Caps the number of captures in a multi-URL run.
--window-size	Sets the browser window size used for capture. The README’s recommended output image is 1200×630; verify the produced dimensions for your setup.
--chrome-path	Points the tool to a Chrome executable when it is not discovered automatically.
--imagemagick-path	Points to the ImageMagick executable when it is not discovered automatically.
--overwrite	Replaces output images that already exist; without it, existing images are skipped.

The README also lists defaults of concurrency 3, quality 100, timeout 60000 milliseconds, WebP output, and ./public/screenshots as the output directory. The project describes its recommended output size as 1200×630. Read the installed version’s help or README for the precise syntax accepted by options whose values vary.

Make repeatable builds

1. Pin the Node.js version at 16 or later in your development environment.
2. Install Chrome and ImageMagick, then confirm their executable paths if automatic discovery fails.
3. Run the CLI against a single page first and inspect the output file and framing.
4. Use --max-screenshots to constrain a sitemap or RSS run while validating it.
5. Keep generated images in the intended public asset directory and use --overwrite when you need to refresh files that the CLI would otherwise skip.

Choose between the hosted API and the local CLI

Decision	ScreenshotMachine API from Bash	og-screenshots local CLI
Where capture runs	Hosted service; your terminal sends an HTTP GET.	Your machine, using local Chrome and ImageMagick.
Credential or setup	Account customer key; protect the secret phrase and use the documented hash for public requests when configured.	Node.js 16+, Chrome, and ImageMagick.
Batch source	The cited API example captures a supplied URL.	Accepts one URL, sitemap, or RSS feed and can process multiple detected URLs.
Operational caveats	Depends on the hosted API and its account configuration.	README says beta, macOS-only testing, and occasional hangs; other platform support is unverified.

Choose the API when you want to make a simple HTTP request from a script without installing a browser stack. Choose the local CLI when you want sitemap or feed discovery and can manage the local dependencies and its stated caveats.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request returns a PNG, JPEG, WebP, or PDF. It accepts cookie and consent banners like a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each of those steps can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. Its MCP server provides screenshot, page information, and PDF capture tools for AI agents.

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

See the ScreenshotNeo API documentation for options and configuration. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for ScreenshotNeo’s free plan.

Troubleshooting

Symptom	Likely cause	What to do
ScreenshotMachine rejects or ignores a request	Missing customer key or, when a secret phrase is configured, missing or incorrect hash.	Check account credentials and follow the API guide’s hash recipe. Keep the secret phrase server-side.
URL with query parameters captures the wrong page	URL was not encoded as a single parameter.	Use --data-urlencode "url=..." in curl, or a URL encoder in other languages.
Image is clipped or has the wrong shape	Requested dimensions or device framing do not suit the page.	Adjust dimension and device, then review the resulting 1200×630 composition for social sharing.
Images or animations are missing in API capture	The page needs more time before capture.	Increase the documented delay option, especially for long pages with images or animation.
Stale ScreenshotMachine image appears	A cached image is being reused within the cache limit.	Set cacheLimit=0 to disable cached results, or choose a shorter cache period.
Local CLI cannot find Chrome	Chrome is absent or not found at the expected executable path.	Install Chrome and pass the correct --chrome-path.
Local CLI cannot find ImageMagick	convert is absent or not discoverable.	Install ImageMagick and set --imagemagick-path to its executable.
Existing output does not change	The CLI skips existing image files by default.	Pass --overwrite for the refresh run.
Local run is slow or appears stuck	Large input set, browser workload, timeout, or the occasional hang documented by the project.	Start with one URL, reduce the batch with --max-screenshots, and check the timeout and dependencies. If it remains stuck, stop the process and retry a smaller run.

Performance, reliability, and cost considerations

Performance

For ScreenshotMachine, capture delay trades waiting time for the chance that late-loading images or animations are ready. Start with the shortest delay that produces a complete card, then increase it for pages that need more time. Avoid requesting a full-page capture when a fixed social card is the goal.

For og-screenshots, concurrency defaults to 3 and timeout to 60000 milliseconds according to its README. Large sitemaps multiply browser work, so validate a small set first and cap the run with --max-screenshots. The project warns of occasional hangs, so do not assume an unattended large run will always finish cleanly.

Reliability

Check that the saved response is actually an image before publishing it. For API scripts, handle network errors and non-success HTTP responses, and avoid treating an error page as a valid image. For local runs, verify Chrome and ImageMagick paths, confirm expected output files, and retain source URLs so failed captures can be retried.

Cost

The cited ScreenshotMachine sources establish the API workflow but do not establish current pricing, so check its account and pricing information directly before estimating usage costs. The local CLI avoids a hosted screenshot API call, but requires you to provide and maintain the local software dependencies and execution environment. ScreenshotNeo’s published plans include 1,000 free shots per month with no card; paid tiers begin at $5 for 3,000 and scale upward. Its features are available on every plan.

FAQ

Is there an official ScreenshotMachine CLI?

The cited official documentation describes a hosted screenshot API and a Bash/curl example. It does not identify a dedicated ScreenshotMachine CLI product.

Which tool accepts a sitemap or RSS feed?

The separate og-screenshots local CLI accepts a page URL, sitemap, or RSS feed as its --url input.

What size should an Open Graph image be?

The og-screenshots README recommends 1200×630. Check the requirements of the social platforms where the image will appear.

Can I run og-screenshots on Windows or Linux?

The project README reports testing only on macOS. Its behavior on other platforms is not established by the cited source.