How to Set a Custom Viewport Size in ScreenshotMachine

To set a custom viewport size in ScreenshotMachine, pass the dimension parameter as WIDTHxHEIGHT, with width first. For example, dimension=1024x768 requests an image at that specified size. The documented width range is 100–1920 pixels; height can be 100–9999 pixels, or full for a full-length page image. ScreenshotMachine’s API documentation describes the parameter and limits.

1. Choose a fixed size or a full-page image

Use a numeric height when you want a fixed-size screenshot, such as 1024x768. Use full as the height when you want the full page at the selected width, such as 1024xfull. A full-page image is not the same as choosing a custom numeric viewport height.

Goal	`dimension`
Fixed 1024 × 768 image	`1024x768`
Phone-sized example	`480x800`
Tablet-sized example	`800x1280`
Full page at 1024 pixels wide	`1024xfull`

These are examples, not a claim that a device preset and dimensions always map to exact CSS viewport coordinates. ScreenshotMachine documents dimension, device, and zoom as separate settings but does not fully specify their interaction in those terms.

2. Set the dimension in the API

The API endpoint is https://api.screenshotmachine.com/. Include your API key, target URL, and dimension. This structural cURL example saves the returned image to a file:

curl -G "https://api.screenshotmachine.com/" \
  --data-urlencode "key=YOUR_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "dimension=1024x768" \
  --data-urlencode "device=desktop" \
  -o screenshot.png

Replace YOUR_KEY with your ScreenshotMachine customer key. URL encoding the parameters protects URLs that contain query strings or reserved characters. The API’s documented example pairs device=desktop with 1024x768; it also lists phone and tablet device values.

Python

ScreenshotMachine’s Python sample uses the same dimension field. This example makes the request and writes the response bytes to a file:

import requests

response = requests.get(
    "https://api.screenshotmachine.com/",
    params={
        "key": "YOUR_KEY",
        "url": "https://example.com",
        "dimension": "1024x768",
        "device": "desktop",
    },
    timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
    image_file.write(response.content)

For a full-length capture, change the dimension value to 1024xfull. ScreenshotMachine’s official Python sample also shows 1366x768 and mentions 1366xfull.

Node.js

Use URLSearchParams to encode the query parameters. This Node.js example saves the response body as an image:

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

const params = new URLSearchParams({
  key: 'YOUR_KEY',
  url: 'https://example.com',
  dimension: '1024x768',
  device: 'desktop',
});

const response = await fetch(`https://api.screenshotmachine.com/?${params}`);
if (!response.ok) {
  throw new Error(`ScreenshotMachine returned HTTP ${response.status}`);
}
await writeFile('screenshot.png', Buffer.from(await response.arrayBuffer()));

Use a response extension and content handling that match the output format configured for your request. The cited dimension documentation establishes sizing; it does not specify every output-format option.

3. Set the size in the online generator

If you are using the web interface instead of the API, provide the target URL, choose a device, enter the desired values in the Width and Height fields, and enable the full-page option only when you want the page’s full length. The online screenshot generator exposes width, height, device, and full-page controls.

4. Understand device and zoom settings

dimension controls the requested width and height. device is a separate setting with the documented values desktop, phone, and tablet. The API documentation’s examples pair desktop with 1024x768, phone with 480x800, and tablet with 800x1280.

zoom is another separate setting. ScreenshotMachine describes zoom=200 as producing an image twice the size at the default zoom. Its documentation also says zoom can be ignored for screenshots smaller than a typical device dimension. If the rendered scale matters, check the resulting image rather than assuming that changing dimension and zoom has a particular CSS-viewport effect.

5. Validate dimensions and full-page captures

Put width first and height second: 1024x768, not 768x1024 unless those are the intended width and height.
Keep numeric width within the documented 100–1920 pixel range.
Keep numeric height within the documented 100–9999 pixel range, or use the literal full.
Use a value such as 1024xfull for full-page height; do not put a numeric height after full.
For long pages that need time for images or animations, ScreenshotMachine recommends increasing delay.
Pass a valid customer key and encode the target URL and other reserved characters in API requests.

6. Troubleshooting

Symptom	Likely cause	What to check
The dimensions are reversed	The value is height-first.	Set `dimension` in width-by-height order, for example `1024x768`.
The requested size is rejected or not applied	A numeric value may be outside the documented range, or the dimension string may be malformed.	Use a width from 100 to 1920 and a height from 100 to 9999, or use `full` as the height. Check the separator and spelling.
The screenshot is much taller than expected	The height is set to `full`.	Use a numeric height, such as `1024x768`, for a fixed-size image.
A full-page result is missing late-loading content	The page may need more time for images or animations.	Increase the request’s `delay`, as recommended in the API documentation.
The output does not look like the chosen device size	`device` and `zoom` are separate controls, and their interaction with dimensions is not fully specified in exact CSS viewport terms.	Check the selected device and zoom settings, then inspect the resulting image. Do not treat the preset as a guarantee of exact viewport coordinates.
The request fails before capture	The API requires a customer key, or the URL or query parameters may not be encoded correctly.	Confirm the key is present and URL-encode the target URL and reserved characters.

7. Performance, reliability, and cost considerations

The main sizing choice is whether to request a fixed height or a full-page image. A full-page result can be substantially taller, so consider the image dimensions and downstream storage or processing needs. For long pages where images or animations need time, increase delay; this adds waiting time to the capture workflow. The cited ScreenshotMachine materials do not establish response-time guarantees, pricing, or a cost per dimension, so check the vendor’s current account details for those specifics.

8. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. Its one-call API accepts a URL and returns an image or PDF. 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://stripe.com -o shot.webp

ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, failed loads, timeouts, and cache hits are never billed, and the response indicates the page verdict and billing status. Its MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 shots.

Create a free ScreenshotNeo account and get 1,000 screenshots a month with no card.

FAQ

Does ScreenshotMachine use a parameter named `viewport`?

The documented API parameter for the requested width and height is dimension.

Can I request a full-page image and choose its width?

Yes. Use the desired width and full for the height, for example 1024xfull.

Does a phone preset guarantee a particular CSS viewport?

The documentation lists a phone device preset and an example dimension, but does not fully specify exact CSS viewport behavior for every device and zoom combination.