How to Set Viewport Size in ScreenshotMachine CLI
Set ScreenshotMachine screenshot dimensions with the dimension parameter, using curl or code. Learn the size limits, full-page option, device modes, and fixes for common issues.
Set ScreenshotMachine’s viewport dimensions with the API parameter dimension=WIDTHxHEIGHT. For example, dimension=1366x768 requests a 1366-by-768 screenshot, while dimension=1024xfull requests a full-page capture 1024 pixels wide. The official materials document an HTTP API and command-line examples using Bash and curl; they do not establish a separate ScreenshotMachine CLI or a --viewport flag. So from a terminal, send the documented API request with curl.
The API reference documents widths from 100 through 1920 pixels and heights from 100 through 9999 pixels; full is also accepted as the height. See ScreenshotMachine’s API parameter reference for the current request options.
1. Set the viewport from the command line with curl
Replace the placeholder key with your ScreenshotMachine API key. The request saves the returned image to screenshot.png.
curl -G "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 "delay=2000" \
--output screenshot.png--data-urlencode safely encodes query values, including URLs that contain characters such as &. Keep the API key out of checked-in scripts and public client-side code. The API requires key and url; the other parameters shown are optional.
Capture the full page
Use full as the height value to capture a long page at a fixed width:
curl -G "https://api.screenshotmachine.com" \
--data-urlencode "key=YOUR_CUSTOMER_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "dimension=1024xfull" \
--data-urlencode "device=desktop" \
--data-urlencode "format=png" \
--data-urlencode "delay=2000" \
--output full-page.pngLong pages can need more time for images and animations to load. The API documentation suggests considering a longer delay, such as 2000 milliseconds or more, for these pages.
2. Use the dimension parameter from Python
This example uses Python’s standard library, so it needs no third-party package. It builds the query string safely, downloads the response, and writes the image.
from urllib.parse import urlencode
from urllib.request import urlopen
params = {
"key": "YOUR_CUSTOMER_KEY",
"url": "https://example.com",
"dimension": "1366x768",
"device": "desktop",
"format": "png",
"delay": "2000",
}
request_url = "https://api.screenshotmachine.com/?" + urlencode(params)
with urlopen(request_url, timeout=90) as response:
image = response.read()
with open("screenshot.png", "wb") as output:
output.write(image)For a full-page image, change "dimension": "1366x768" to "dimension": "1024xfull". ScreenshotMachine’s official Python example also passes dimension as an option. See its Python example.
3. Use the dimension parameter from Node.js
This example uses the built-in fetch available in current Node.js releases and writes the response bytes to a PNG file.
const { writeFile } = require('node:fs/promises');
const params = new URLSearchParams({
key: 'YOUR_CUSTOMER_KEY',
url: 'https://example.com',
dimension: '1366x768',
device: 'desktop',
format: 'png',
delay: '2000',
});
const response = await fetch(
`https://api.screenshotmachine.com/?${params}`,
{ signal: AbortSignal.timeout(90000) }
);
if (!response.ok) {
throw new Error(`Screenshot request failed: HTTP ${response.status}`);
}
const image = Buffer.from(await response.arrayBuffer());
await writeFile('screenshot.png', image);To request a full page, set dimension: '1024xfull'. For production code, check the response content type as well as the status before treating the body as an image, since an API error response should not be saved as a valid screenshot.
4. Choose dimensions, device mode, and timing
| Setting | What it controls | Documented details |
|---|---|---|
dimension |
Requested screenshot width and height | Format is widthxheight; width 100–1920; height 100–9999; full is accepted for height. Default: 120x90. |
device |
Device mode | Options are desktop, phone, and tablet; default is desktop. |
delay |
Wait time before capture | Documented range is 0–10000 ms in allowed increments; documented default is 200 ms. Longer waits can help pages with late-loading content. |
zoom |
Page zoom | Default is 100%; documented values are 10–400. Zoom is separate from viewport dimensions and is ignored for screenshots smaller than a typical device dimension. |
format |
Image format | Examples use PNG; consult the API reference for supported response formats. |
Device mode and dimensions are separate request settings. The documentation gives these combinations as examples: desktop with 1024x768, phone with 480x800, and tablet with 800x1280. You can choose a different supported size; do not assume selecting a device automatically fixes the viewport to one size.
Pick dimensions for the result you need
- Match a target viewport: provide the exact width and height, such as
1366x768. - Make a thumbnail: use a smaller valid size, such as
320x240. - Capture a tall page: use a valid width and
fullheight, such as1024xfull. - Check a mobile layout: set both a suitable narrow dimension and
device=phone; dimensions and device mode are distinct.
5. Troubleshooting
| Symptom | Likely cause | What to do |
|---|---|---|
| Request is rejected or does not produce the expected image | Dimension is malformed or outside documented limits. | Use WIDTHxHEIGHT, for example 1366x768. Keep width between 100 and 1920 and numeric height between 100 and 9999; use the literal full for full-page height. |
| The image shows an unexpected layout | Device mode and dimensions were treated as one setting, or the target site responds differently to the selected device mode. | Set both device and dimension explicitly, then compare a desktop, phone, or tablet request. |
| Images or animations are missing | The capture happened before the page finished rendering. | Increase delay within the documented range. For a long page, the reference suggests trying 2000 ms or more. |
| The result is unexpectedly zoomed | zoom changes page scale; it does not define the viewport. |
Set dimension to the required size and use zoom=100 unless you intentionally need another documented zoom value. |
| The downloaded file is not a usable image | The request may have returned an error response, or the output extension does not match the requested format. | Check the HTTP status and response before writing it, verify the key and target URL, and align the filename extension with format. |
| The terminal command treats URL characters as separators | Query values were concatenated without encoding. | Use curl’s --data-urlencode for each field rather than manually concatenating a query string. |
6. Performance, reliability, and cost considerations
A larger viewport produces a larger image, while full can produce a particularly tall file. Use the smallest width and height that satisfy the downstream task to limit transfer and storage. Full-page captures and pages with late-loading media may take longer; increase delay only when the rendered result requires it. The documented delay maximum is 10000 ms.
For automated workflows, set a client timeout, check HTTP status and content type, and retry only transient failures with a bounded retry policy. Avoid blindly retrying invalid dimensions or credentials. The cited API reference does not provide a performance benchmark or a cost figure relevant to a particular capture, so check ScreenshotMachine’s current account and pricing details for those specifics.
Or skip the browser setup
ScreenshotNeo is a screenshot API and MCP server for developers. One GET request returns an image or PDF; use width and height to set a viewport. See the ScreenshotNeo API documentation for its request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com \
-d width=1366 \
-d height=768 \
-o shot.webpScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before capture. Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots each month with no card; paid plans start at $5 for 3,000.
Sign up free and get 1,000 screenshots a month with no card.
FAQ
Is there an official ScreenshotMachine CLI viewport flag?
The official materials reviewed document API requests and command-line curl examples, but no separate CLI viewport flag. From a terminal, use curl and pass dimension as a request parameter.
Does dimension=1024xfull mean unlimited page height?
It requests a full-length page at 1024 pixels wide. The reference allows the full height value but does not describe it as an unlimited capture guarantee.
Does device=phone set the viewport dimensions?
Device mode and dimension are separate options. Specify both when the intended device context and exact size matter.
Can I use zoom instead of setting the viewport?
No. zoom controls page scale; dimension specifies the screenshot size. Configure the relevant parameter for each requirement.
