To capture a webpage with Screenshot Machine, send an HTTP GET request to https://api.screenshotmachine.com/ with your customer key and target url. Save the binary response as an image file. Set dimension, device, format, delay, cacheLimit, and zoom to control the result, and inspect the X-Screenshotmachine-Response header when the service returns an error image.
Make your first Screenshot Machine capture
Create a Screenshot Machine account and copy your customer API key. Keep the key on a server or in an environment variable rather than placing it in browser JavaScript. The required request parameters are:
key: your customer key.url: the webpage to render.
This cURL request asks for a 1,366 by 768 desktop PNG, waits 200 milliseconds, bypasses the normal cache, and writes the response to capture.png:
curl -Gs 'https://api.screenshotmachine.com/'
--data-urlencode 'key=YOUR_CUSTOMER_KEY'
--data-urlencode 'url=https://example.com'
--data-urlencode 'dimension=1366x768'
--data-urlencode 'device=desktop'
--data-urlencode 'format=png'
--data-urlencode 'cacheLimit=0'
--data-urlencode 'delay=200'
--data-urlencode 'zoom=100'
> capture.pngReplace both placeholders before running it. --data-urlencode is important when the target contains a query string, spaces, non-ASCII characters, or CSS selector characters. The API is based on an HTTP GET request, so the response body is the image (including an error image when the request cannot be processed).
Check the response before treating it as a successful image
Although the output file may have an image extension, read the X-Screenshotmachine-Response response header. A successful capture should not carry one of the documented error codes. In production, save the header and HTTP status in your logs, verify the content type, and only publish the file after those checks.
Python and Node.js examples
Python with requests
import requests
params = {
"key": "YOUR_CUSTOMER_KEY",
"url": "https://example.com",
"dimension": "1366x768",
"device": "desktop",
"format": "png",
"cacheLimit": "0",
"delay": "200",
"zoom": "100",
}
response = requests.get(
"https://api.screenshotmachine.com/",
params=params,
timeout=90,
)
response.raise_for_status()
error_code = response.headers.get("X-Screenshotmachine-Response")
if error_code:
raise RuntimeError(f"Screenshot Machine error: {error_code}")
with open("capture.png", "wb") as image_file:
image_file.write(response.content)The library URL-encodes the query parameters for you. A 90-second timeout gives a slow page time to render without allowing a request to hang indefinitely.
Node.js using the built-in fetch API
const params = new URLSearchParams({
key: 'YOUR_CUSTOMER_KEY',
url: 'https://example.com',
dimension: '1366x768',
device: 'desktop',
format: 'png',
cacheLimit: '0',
delay: '200',
zoom: '100'
});
const response = await fetch(`https://api.screenshotmachine.com/?${params}`, {
signal: AbortSignal.timeout(90000)
});
if (!response.ok) {
throw new Error(`HTTP ${response.status}`);
}
const errorCode = response.headers.get('X-Screenshotmachine-Response');
if (errorCode) {
throw new Error(`Screenshot Machine error: ${errorCode}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(fs => fs.writeFile('capture.png', image));Use Node.js 18 or a later release for the global fetch implementation. For older versions, install and import a fetch-compatible HTTP client.
Choose the viewport and device
The dimension value is written as widthxheight. Documented widths range from 100 to 1,920 pixels. Heights range from 100 to 9,999 pixels, or you can use full for a full-page image.
| Goal | Parameters | What it does |
|---|---|---|
| Desktop viewport | dimension=1024x768&device=desktop |
Renders a 1,024 by 768 desktop view. |
| Phone viewport | dimension=480x800&device=phone |
Uses a narrow phone-sized viewport. |
| Tablet viewport | dimension=800x1280&device=tablet |
Uses a tablet-sized viewport. |
| Full page | dimension=1024xfull |
Captures the page vertically at 1,024 pixels wide. |
The documented default is 120x90 with desktop. That tiny default is rarely suitable for a production capture, so specify a useful dimension explicitly. Full-page captures can be tall; the vendor suggests increasing the delay for long pages containing images or animations.
Set image format, freshness, waiting, and zoom
Output format
format accepts jpg, png, and gif. JPG is the documented default. PNG is generally preferable for interface text and sharp edges, while JPG can produce smaller photographic files. GIF is available when that output is specifically required.
Cache behavior
cacheLimit controls how old a cached capture may be. It accepts 0 through 14 days and supports decimal values for shorter periods. The documented default is 14 days. Set cacheLimit=0 when each request must ask for a fresh render; use a positive value when reusing a recent capture reduces work and latency.
Render delay
delay is the post-load wait in milliseconds. Documented values run from 0 through 10,000, with a default of 200 milliseconds. Increase it when client-side charts, fonts, lazy images, or animations are not ready at capture time. A longer delay does not guarantee that a page requiring login or an unavailable third-party resource will render.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Zoom
zoom accepts 10 to 400 percent and defaults to 100. A value of 200 can produce a two-times larger result. The documentation warns that zoom is ignored below typical device dimensions, so combine it with a sufficiently large viewport rather than relying on zoom to compensate for a very small one.
Interact with the page or capture only part of it
Click or hide CSS-selected elements
Use click to trigger a CSS-selected element before the screenshot, such as a tab or a menu button. Use hide to remove selected elements, including a cookie banner or an overlay. Reserved characters in selectors, especially #, must be percent-encoded. With cURL, pass these values through --data-urlencode.
Capture one element
selector captures the DOM element matching a CSS selector instead of the complete viewport. This is useful for a product card, chart, or invoice section. An invalid selector produces the documented invalid_selector error.
Crop a viewport rectangle
crop takes x,y,width,height pixel coordinates within the viewport. It is different from selector: crop works on screen coordinates, while selector works on the rendered DOM. A malformed or out-of-range crop returns invalid_crop.
The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREERepair Windows errors before they cause bigger problemsFix Now →Control language, cookies, and the request identity
Use accept-language to send a preferred language header, for example en-US or fr-FR. This can change localized text, date formats, and currency displayed by the page. It does not translate a site that has no translation for that language.
The cookies parameter accepts semicolon-separated name/value pairs. URL-encode the complete value, especially when a cookie contains punctuation. The user-agent parameter changes the user-agent header and can emulate a device profile, but match it with a sensible viewport; changing only the string does not reproduce every behavior of a physical device.
Authentication support is not fully established in the documentation. An invalid_url response can mean the target requires authorization, so do not assume that every login-protected application can be captured. Test access with a non-sensitive page and avoid putting passwords or session tokens in URLs.
Protect a key when calling from public HTML
A direct browser request exposes a customer key. Screenshot Machine documents a safeguard for this case: set a secret phrase and calculate an MD5 hash from the target URL followed by that secret phrase. Once the secret phrase is enabled, requests with a missing or incorrect hash are ignored.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchThis mechanism is a request check, not a replacement for good credential handling. Prefer a server-side proxy where possible, keep the secret out of source control, rotate credentials if exposed, and never log full URLs that contain private tokens.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Troubleshoot error-image responses
| Header code | Likely cause | Fix |
|---|---|---|
missing_key |
The required key was omitted. | Send key and confirm the environment variable is populated. |
missing_url |
No target URL was supplied. | Send a complete https:// or http:// URL. |
invalid_key |
The credential is wrong or inactive. | Copy the current customer key and remove surrounding whitespace. |
invalid_hash |
The public-request hash does not match. | Recompute the MD5 from URL plus secret phrase and encode the value. |
invalid_url |
The URL is malformed, blocked, or requires authorization. | URL-encode it, verify it opens without a login, and check redirects. |
no_credits |
The account has exhausted its credits. | Check the account and wait for renewal or obtain additional credits. |
invalid_selector |
The CSS selector is invalid or matches an unusable target. | Test the selector in browser developer tools and encode reserved characters. |
invalid_crop |
The crop coordinates are malformed or outside the viewport. | Use comma-separated numeric coordinates within the requested dimensions. |
system_error |
A generic service-side failure occurred. | Retry carefully, record the header and parameters, and contact the vendor if it persists. |
If the page is blank, first try a longer delay, a non-cached request, and a viewport matching the site’s responsive breakpoints. Then test the URL without cookies or custom headers to isolate whether request context is causing the failure. Keep retries bounded so a persistent error does not create an uncontrolled request loop.
Operational guidance for reliable captures
- Make rendering deterministic: pin
dimension,device, language, cookies, and zoom for repeatable visual comparisons. - Separate freshness from speed: use a cache limit for stable pages and zero only for workflows that require current content.
- Allow for asynchronous content: increase delay for long pages, images, and animations, then validate the resulting file rather than assuming completion.
- Log diagnostics: retain the request ID or URL, HTTP status, response header, selected options, and elapsed time. Do not log secret keys or sensitive cookies.
- Plan for unsupported access: authorization-required pages may return
invalid_url; design a fallback rather than promising universal coverage.
The vendor material does not provide a named, dated benchmark for latency, success rate, or reliability. Treat response time and compatibility as properties to measure in your own workload, not as guaranteed figures.
Or skip the browser setup: ScreenshotNeo
If you want a hosted API with cleanup and automation features built in, ScreenshotNeo accepts one GET request and returns a PNG, JPEG, WebP, or PDF. Before capture it accepts cookie and consent banners as a visitor and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each cleanup step can be disabled. Bot checks, CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and the response identifies the result with X-Page-Verdict and X-Billed headers. It also provides an MCP server for Claude, Cursor, and other MCP clients, with take_screenshot, get_page_info, and capture_pdf tools.
Do these 3 things before closing this tab:
1Scan for outdated or missing drivers - takes under a minute2Clear out junk files and repair common Windows errors3Fix the driver behind crashes, sound loss and screen glitchescurl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpSee the ScreenshotNeo documentation for the full parameter list. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.
Screenshot Machine or ScreenshotNeo?
Screenshot Machine is a straightforward choice when its documented GET parameters, selector controls, and account model match your integration. ScreenshotNeo is the alternative to try first when you need consent-banner and popup removal, explicit billing verdicts, an MCP workflow for AI agents, PDF output, or a free allowance with no card.
Frequently Asked Questions
Can Screenshot Machine capture a page behind a login?
The documentation does not fully establish supported authentication workflows. An authorization-required target can return invalid_url, so verify your specific access pattern rather than assuming it is supported.
How do I request a full-page screenshot?
Set dimension with full as the height, such as 1024xfull. Increase delay for long pages with images or animations.
Free tools Windows power users keep installed
One-click scans. No signup required.
Where do I find the reason an image is an error?
Read the X-Screenshotmachine-Response header and map its code to the documented causes, such as missing_key, invalid_selector, or no_credits.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
