How to Use ScreenshotMachine CLI to Capture a Full Webpage

Direct answer: ScreenshotMachine’s official material documents command-line use through a shell script that calls its screenshot API with curl; it does not document a separate ScreenshotMachine CLI executable. To capture a full webpage, set dimension to a width followed by xfull, such as 1366xfull, and save the response body to an image file. You need a ScreenshotMachine customer key and the page URL. ScreenshotMachine API documentation

Capture a full webpage with curl

Run this Bash example from a terminal. Replace the key and target URL, then save the script as capture.sh if you want to reuse it.

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

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

ARGS=(
  --data-urlencode "key=$CUSTOMER_KEY"
  --data-urlencode "dimension=1366xfull"
  --data-urlencode "device=desktop"
  --data-urlencode "format=png"
  --data-urlencode "delay=2000"
  --data-urlencode "url=$URL"
)

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

Make it executable and run it:

chmod +x capture.sh
./capture.sh

The command uses --data-urlencode so query strings, ampersands, and other reserved characters in the target URL are encoded correctly. The -G option sends the supplied data as query parameters, and -s suppresses curl’s progress meter. The documented vendor example redirects the API response to a file; this version uses -o to name that file explicitly. -f makes curl return a failure for HTTP error responses, but API-level error images may still need to be identified from the response header.

Choose full-page dimensions, device, and format

The API’s full-page form is widthxfull. The documented width range is 100 to 1920 pixels. For example, 1024xfull or 1366xfull requests the full page at that width. A value such as 1366x768 is a fixed viewport-sized capture, not a full-length screenshot. Parameter reference

Setting	Choices and behavior	When to adjust it
dimension	Width from 100 to 1920, followed by xfull for full page; a numeric height requests a bounded capture.	Use a width that matches the intended desktop or responsive layout.
device	desktop, phone, or tablet; desktop is the documented default.	Choose the responsive rendering to capture. The vendor examples include 1024×768 desktop, 480×800 phone, and 800×1280 tablet dimensions.
format	jpg, png, or gif; JPG is the documented default.	Choose the format according to downstream use, and keep the output filename extension consistent.
delay	Documented values run from 0 through 10000 milliseconds at listed increments.	Increase the wait for pages with late images, animation, or other content that appears after initial load. ScreenshotMachine recommends a longer delay, such as 2000 ms or more, for long pages with many images or animations.
cacheLimit	0 through 14 days.	Use 0 when you need a fresh result; a higher value permits a cached result up to that age.
zoom	10% through 400%; default is 100%.	Adjust scale when needed. The API guide says zoom is ignored for screenshots smaller than the typical dimension associated with the selected device.

Optional page and request controls

The API documentation also describes controls for pages that need a particular session, language, layout, or capture region. Add them as encoded parameters to the same curl request.

• cookies: pass cookie state for pages where a session changes what is visible. URL-encode reserved characters in the value.
• accept-language: request a particular language variant.
• user-agent: set the user-agent string used for the request.
• click: click an element selected by CSS before capture.
• hide: hide selected elements, such as a cookie banner.
• selector: capture a particular DOM element rather than the entire page.
• crop: select a rectangle from the viewport.

For example, to set a language header parameter, add --data-urlencode "accept-language=en-US" to the ARGS array. For cookie values or selectors containing special characters, continue to use --data-urlencode. The controls change what the API requests or captures; they do not replace checking the resulting image when page content depends on scripts, session state, or timing.

Credentials and request signing

The request requires a customer key and target URL. ScreenshotMachine says the customer key is available after account signup. If a secret phrase is configured, its guide describes an MD5 hash calculated from the URL concatenated with that phrase; requests with a missing or incorrect hash are ignored when a secret phrase is set. Follow the current API documentation for the exact hash parameter and construction. Keep the key and secret phrase in environment variables or a private secret store. Do not commit them to a public repository or expose them in client-side code. ScreenshotMachine API documentation

Call the same API from Python

ScreenshotMachine’s official Python sample repository shows a language integration, not a standalone CLI. This compact example sends the documented API parameters and writes the response body to a PNG file. Install the dependency with python -m pip install requests, set the environment variables, and run the script.

import os
import requests

key = os.environ["SCREENSHOTMACHINE_KEY"]
url = os.environ.get("TARGET_URL", "https://example.com")

response = requests.get(
    "https://api.screenshotmachine.com",
    params={
        "key": key,
        "url": url,
        "dimension": "1366xfull",
        "device": "desktop",
        "format": "png",
        "delay": 2000,
        "cacheLimit": 0,
    },
    timeout=90,
)
response.raise_for_status()
with open("output.png", "wb") as image_file:
    image_file.write(response.content)

print("Saved output.png")

Set SCREENSHOTMACHINE_KEY and optionally TARGET_URL in your shell before running it. The 90-second timeout is a client-side limit in this example, not a ScreenshotMachine service guarantee. Review the response headers if the saved payload is not the expected image.

Call the same API from Node.js

This example uses the built-in fetch available in current Node.js releases. It constructs query parameters safely and writes the returned bytes to disk.

import { writeFile } from "node:fs/promises";

const key = process.env.SCREENSHOTMACHINE_KEY;
if (!key) throw new Error("Set SCREENSHOTMACHINE_KEY first");

const params = new URLSearchParams({
  key,
  url: process.env.TARGET_URL ?? "https://example.com",
  dimension: "1366xfull",
  device: "desktop",
  format: "png",
  delay: "2000",
  cacheLimit: "0",
});

const response = await fetch(`https://api.screenshotmachine.com/?${params}`, {
  signal: AbortSignal.timeout(90_000),
});
if (!response.ok) {
  throw new Error(`Screenshot request failed: HTTP ${response.status}`);
}
await writeFile("output.png", Buffer.from(await response.arrayBuffer()));
console.log("Saved output.png");

As with the Python example, the client timeout is your own limit. Node’s response.ok check catches HTTP-level errors; inspect API response headers too if an error image is returned with a successful HTTP status.

Or skip the browser setup

For a full-page capture with ScreenshotNeo, send one GET request with the URL and save the returned image. The API supports PNG, JPEG, and WebP output. See the ScreenshotNeo API documentation for request options.

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

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, and failed loads are never billed; the response identifies the page verdict and billing status. Its MCP server lets AI agents use screenshot, page-info, and PDF tools. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots.

Sign up free for 1,000 screenshots a month, with no card.

Troubleshooting

Symptom	Likely cause	What to do
The saved file contains an error image.	The request may have an invalid or missing key, URL, or hash. The API guide says error responses can be identified with the X-Screenshotmachine-Response header.	Inspect that header and check the key, URL encoding, and signing configuration. Documented codes include invalid_hash, invalid_key, invalid_url, and missing_key.
Page content or images are missing.	Assets or animations may not have finished before capture.	Increase delay within the documented choices. The vendor recommends a longer delay for long pages with many images or animations.
The screenshot has the wrong layout.	The selected device or width may trigger another responsive breakpoint.	Set device and dimension deliberately, then capture again.
The output looks stale.	A cached response may be allowed by cacheLimit.	Set cacheLimit=0 when a fresh capture is required.
The output file extension does not match its contents.	The requested format and filename extension differ.	Keep format and the output extension aligned, for example format=png with output.png.
Shell arguments break on a URL with query parameters.	Reserved characters such as & were not encoded correctly.	Pass values with curl’s --data-urlencode as in the example instead of assembling an unescaped query string.

Performance, reliability, and cost considerations

• Capture time: Longer delays give late-loading content more time to appear but add waiting time to each request. Start with a short delay for simple pages and raise it when the result shows unfinished content.
• Full-page size: A taller page can produce a larger image and take longer to process or transfer. Choose only the width needed for the intended use, and consider a fixed-height capture when the task is specifically about the initial viewport.
• Freshness: A nonzero cacheLimit can avoid asking for a fresh capture on every request, while 0 is the documented choice when freshness matters. Check the configured age against how quickly the target page changes.
• Retries: For automation, distinguish transport failures from API error images by checking HTTP status and X-Screenshotmachine-Response. Retry transient network failures with a bounded backoff; correct invalid credentials or parameters before retrying.
• Cost: The research sources establish that a customer key is required but do not provide plan prices or usage limits. Check ScreenshotMachine’s current account or pricing information before estimating production costs.

FAQ

Is there an official ScreenshotMachine CLI program?

The reviewed official material documents a shell and curl workflow that calls the hosted API, plus Python and Node.js samples. It does not document a separate command-line executable.

What does 1366xfull mean?

It requests a full-length page capture at a width of 1366 pixels. Replace the width with a value in the documented 100–1920 range.

Can I capture only one element instead of the full page?

Yes. The API guide documents a selector parameter for capturing a selected DOM element. Full-page capture uses the dimension value ending in xfull.

How can I confirm whether the API returned an error?

Check the HTTP response and the X-Screenshotmachine-Response header. The guide lists error codes including invalid_key and invalid_url.

Sources

• ScreenshotMachine Website Screenshot API documentation — shell example, parameters, and error responses.
• ScreenshotMachine Python sample repository.
• ScreenshotMachine Node.js sample repository.
• ScreenshotMachine homepage.