ScreenshotMachine CLI vs wkhtmltoimage for HTML to PDF Screenshots

The tools in this title do not produce the same output in the documented workflows. Screenshot Machine’s “CLI” is a curl command that calls its hosted PDF API. wkhtmltoimage is a local command-line tool for converting HTML into an image. If you need a local PDF, compare Screenshot Machine’s PDF API with wkhtmltopdf, the related local command. If you need an image, compare Screenshot Machine’s screenshot API with wkhtmltoimage.

Quick choice: use Screenshot Machine when you want a hosted PDF conversion with its documented paper and page controls and are comfortable sending a URL and API key to a remote service. Use wkhtmltoimage when you need a local image file and its Qt WebKit behavior fits your pages. Use wkhtmltopdf for local PDF output. The available documentation does not establish a current winner for fidelity, speed, or dynamic-site support; compare both against representative pages from your own workload.

For a managed screenshot API to evaluate first, ScreenshotNeo offers clean screenshots, bills only clean shots, and has a $5 paid plan for 3,000 shots.

1. What each command actually does

Workflow	Runs where	Output	What to know
Screenshot Machine PDF API via curl	Rendering is provided by a hosted HTTP API; curl sends the request	PDF	Requires an API key and network access. The provider documents paper, orientation, media, delay, scale, cookies, user-agent, and selector controls. Screenshot Machine PDF API documentation
wkhtmltoimage	Local command-line program	Image, such as PNG or JPEG	Not the PDF-output command. Its manual describes image format and quality settings, viewport dimensions, cropping, JavaScript, cookies, headers, and local-file access. Debian wkhtmltoimage manual
wkhtmltopdf	Local command-line program	PDF	The related command for local PDF generation. The upstream project describes both commands as headless tools based on Qt WebKit. wkhtmltopdf project
Screenshot Machine screenshot API	Hosted HTTP API	Image	This is the provider’s image-output workflow, distinct from its PDF endpoint. Screenshot Machine screenshot API documentation

Screenshot Machine’s Bash example is a command-line integration, not a standalone renderer installed on your machine. Its PDF documentation describes requests to https://pdfapi.screenshotmachine.com/. In contrast, the wkhtml tools are local programs: install and package the relevant binary, then invoke it with an input and output path.

2. Create a PDF with Screenshot Machine’s hosted API

Use the PDF endpoint when a hosted conversion is acceptable. Replace YOUR_API_KEY and the target URL. Keep the API key out of source control, shell history where practical, and client-side code.

curl -Gs "https://pdfapi.screenshotmachine.com" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "paper= A4" \
  -o output.pdf

Remove the space before A4 if copying the sample literally: the value should be A4. A cleaner command is:

curl -Gs "https://pdfapi.screenshotmachine.com" \
  --data-urlencode "key=YOUR_API_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "paper=A4" \
  -o output.pdf

The API documentation’s required pattern is a GET request with query parameters and a PDF response saved to a file. Confirm the current parameter names and accepted values in the provider documentation before building a production integration.

PDF controls documented by Screenshot Machine

• Paper: letter, legal, ledger, tabloid, and A-series paper values.
• Orientation: portrait or landscape.
• Media: screen or print styles.
• Appearance: background selection and scale.
• Timing: a delay before capture.
• Page interaction: selector-triggered click and selector-based hide controls. The documentation describes clicking a cookie banner and hiding page elements.
• Request context: cookies, language, and user-agent parameters.

These are provider-documented options, not a guarantee that every site will render as desired. Validate the output for the sites and authentication state that matter to your use case.

3. Create a local image with wkhtmltoimage

The documented command form is wkhtmltoimage [OPTIONS]... <input file> <output file>. Depending on the installed build, the input can be a local HTML file or a URL. This example captures a URL into a PNG:

wkhtmltoimage \
  --format png \
  --width 1280 \
  --javascript-delay 1000 \
  https://example.com \
  page.png

To create a JPEG and set its quality:

wkhtmltoimage \
  --format jpg \
  --quality 85 \
  --width 1280 \
  https://example.com \
  page.jpg

For a local file, use its path as the input. If that HTML loads local stylesheets, fonts, or images, check the installed build’s local-file access policy and allow only the paths it needs. The manual documents --disable-local-file-access and repeatable --allow paths.

Useful wkhtmltoimage options

Need	Documented controls	Practical note
Image type and compression	--format, --quality	The manual documents quality from 0 to 100. Quality is relevant to supported lossy output formats.
Viewport and crop	--width, --height, --crop-x, --crop-y, --crop-w, --crop-h	The width is a guide unless strict width behavior is enabled by the build’s options. Check wkhtmltoimage --extended-help.
JavaScript timing	--disable-javascript, --enable-javascript, --javascript-delay, --window-status, --run-script	A fixed delay can be too short or unnecessarily long. A page-controlled status condition may fit pages that expose one.
Cookies and request headers	--cookie, --cookie-jar, --custom-header, header propagation controls	Use only credentials and headers appropriate for the target. Avoid leaking secrets into logs or process listings.
Network access	--proxy, authentication options, SSL client-certificate options	These affect how the local program reaches protected or proxied resources; behavior depends on the installed build.
Local resources	--disable-local-file-access, --allow	Restrict access to the directories needed by the input document.
Styling and images	--user-style-sheet, --images, --no-images, --zoom	Use stylesheet injection or zoom to adjust the image output when the page itself cannot be changed.

Run wkhtmltoimage --extended-help and wkhtmltoimage --version on the exact binary you deploy. Options and packaging can vary by build.

4. Create a local PDF with wkhtmltopdf

For a local PDF, use the sibling program rather than trying to give wkhtmltoimage a PDF filename. A basic command is:

wkhtmltopdf https://example.com output.pdf

For a local HTML file:

wkhtmltopdf ./report.html output.pdf

wkhtmltopdf has its own PDF-oriented options and page settings. Consult the usage documentation for the installed version rather than assuming that image options for wkhtmltoimage map directly to PDF settings. wkhtmltopdf usage documentation

The upstream GitHub repository was archived read-only on January 2, 2023. That is a maintenance consideration for the upstream project; check the exact package, binary, or fork you plan to deploy. Repository status

5. Compare the tradeoffs that affect a real deployment

Deployment and data flow

The Screenshot Machine PDF workflow sends a URL and request parameters to a hosted service. It needs an API key and network connectivity, and the document is rendered by the remote service. The local wkhtml commands need an installed binary and its runtime dependencies, but the documented execution is on the machine invoking the command. Choose based on your deployment constraints and the data-handling requirements of your application.

Output and rendering controls

For PDF, compare the Screenshot Machine PDF endpoint with wkhtmltopdf. For images, compare Screenshot Machine’s screenshot API with wkhtmltoimage. Screenshot Machine documents paper, orientation, and screen/print media for its PDF flow; wkhtmltoimage documents image formats, viewport sizing, cropping, and image quality. Similar-sounding options do not make their outputs or rendering engines equivalent.

Fidelity, speed, and dynamic pages

The documentation used here lists configuration options but does not include a controlled current comparison of rendering fidelity, speed, or dynamic-site support. Do not select a winner on those grounds without testing. Build a small test set that covers your actual page types: long pages, custom fonts, lazy-loaded images, JavaScript-rendered content, authenticated pages, cookie banners, and print-specific styles. Compare the resulting files and the time and operational work required by your actual setup.

Maintenance

The upstream wkhtmltopdf repository is archived. If you choose a local renderer, identify the source and maintenance status of the package or fork, pin the build, and verify behavior after any upgrade. A hosted API avoids operating that local binary, but introduces an external service and network dependency.

Pricing and operating costs

Screenshot Machine’s pricing page lists a free tier with 100 fresh screenshots per month, Basic at €9 per month for 2,500, Pro at €59 per month for 20,000, and Enterprise at €99 per month for 50,000. These are provider-listed figures and may change; check the current pricing page before deciding.

The wkhtmltopdf project documentation identifies the local tools as open source under LGPLv3. That does not make operation cost-free: account for installation, dependency packaging, capacity, monitoring, and maintenance, and review the license obligations that apply to your distribution. Project and license information

6. A practical selection checklist

1. Name the output. PDF: evaluate Screenshot Machine’s PDF API or local wkhtmltopdf. Image: evaluate Screenshot Machine’s screenshot API or local wkhtmltoimage.
2. Decide where rendering may happen. A hosted request needs network access and an API key. A local renderer needs a packaged binary and runtime support.
3. List required controls. For example, paper size, print media, cookies, viewport, cropping, headers, or local resource access.
4. Test representative pages. Check the exact pages and authentication conditions you expect in production. The documentation alone does not settle fidelity or speed.
5. Plan for failures. Decide how your application detects unsuccessful responses, incomplete output, timeouts, missing assets, and renderer process failures.
6. Review maintenance and cost. Compare the current hosted plan with the staff time and infrastructure needed to package and maintain the local tool.

7. Troubleshooting

Symptom	Likely cause	What to try
You expected a PDF from wkhtmltoimage	It is the image-output command.	Use wkhtmltopdf for local PDF output, or call a PDF API.
The Screenshot Machine curl request fails	Missing or invalid API key, malformed query parameters, or network failure.	Check the key and parameter names against the official PDF docs, URL-encode values, and inspect curl’s exit status and response before treating the file as a valid PDF.
Output file exists but is not a valid PDF	The response may contain an error rather than a PDF.	Capture response headers and inspect the response body in a safe debugging environment; do not assume that a redirected file means conversion succeeded.
JavaScript content is missing in a local image	JavaScript may be disabled, unsupported by the specific build or page, or still running when capture begins.	Check JavaScript settings, try a documented delay or window-status condition, and test the installed binary against the target page.
Local CSS, fonts, or images are missing	Local-file access policy, incorrect relative paths, or inaccessible remote assets.	Check paths, enable access only where appropriate, and allow required directories with --allow. Confirm network access for remote assets.
Screenshot dimensions or crop are unexpected	Viewport dimensions and crop coordinates are different controls; width may be a guide in some builds.	Review the installed command’s extended help, set viewport and crop deliberately, and validate the resulting dimensions.
Authenticated content is absent	The renderer request lacks the session cookies, headers, or authentication context.	Provide the documented cookies or headers to the chosen workflow, and confirm the target URL is reachable under that context.
Output differs between machines	Different binaries, packaging, fonts, or runtime dependencies can change behavior.	Pin and record the exact package/build and required fonts; compare using the same inputs and environment.

8. Or skip the browser setup

For a hosted screenshot call, ScreenshotNeo returns an image or PDF from one GET request. Its capture flow accepts cookie and consent banners and removes more than 60 known consent platforms, newsletter popups, and chat widgets before capture; each step can be turned off. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Responses include X-Page-Verdict and X-Billed headers. It also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents.

Here is a runnable cURL request. Replace the target URL and API key. See the ScreenshotNeo API documentation for the available formats and options.

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

Python:

import requests

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

Node.js:

const q = new URLSearchParams({
  access_key: 'YOUR_API_KEY',
  url: 'https://example.com'
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
const bytes = new Uint8Array(await res.arrayBuffer());
await (await import('node:fs/promises')).writeFile('shot.webp', bytes);

Cookie banners, popups, and chat widgets are removed before the shot. Bot checks, blank pages, and failed loads are never billed. The MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000. Sign up free for ScreenshotNeo.

9. FAQ

Can wkhtmltoimage create a PDF?

The documented tool creates images. Use its sibling, wkhtmltopdf, for local PDF generation.

Is Screenshot Machine’s CLI a local executable?

The documented command-line example uses curl to call a hosted PDF API. It is not documentation of a self-contained local rendering binary.

Which one is faster or more accurate?

The sources used here do not provide a controlled comparison. Measure the exact pages, output type, and deployment you need.

Is wkhtmltopdf still maintained upstream?

The upstream GitHub repository is archived and read-only. Check the maintenance status of the particular package or fork you plan to use.

Does the hosted API require internet access?

Yes. The documented flow makes an HTTP request to the service and requires an API key.