How to Set a Custom Viewport Size in ScreenshotAPI.net
Set ScreenshotAPI.net’s browser viewport with width and height parameters. Learn how to choose dimensions, distinguish viewport capture from full-page and crop operations, and troubleshoot common issues.
Set the browser viewport for a ScreenshotAPI.net capture by passing integer width and height request parameters. For example, add width=1440&height=900 to render the page at a 1440-by-900 browser window size. The viewport is the browser window used to lay out the page; it is separate from the dimensions of the returned image and from whether the capture includes the whole page.
ScreenshotAPI.net’s product page shows a request to https://shot.screenshotapi.net/v3/screenshot with width=1680&height=876. The examples below use that documented endpoint form; check your account’s current API documentation if your integration uses a different endpoint or version. ScreenshotAPI.net’s product page and its Playground describe width and height as browser viewport settings.
1. Choose the viewport dimensions
Pick dimensions that represent the browser window or responsive breakpoint you want to inspect. ScreenshotAPI.net gives 390×844, 1024×768, 1440×900, and 1680×876 as examples. They are starting points, not required device standards.
| Example view | Width | Height | Use |
|---|---|---|---|
| Mobile-style | 390 | 844 | Check a narrow responsive layout |
| Tablet-style | 1024 | 768 | Check an intermediate layout |
| Desktop-style | 1440 | 900 | Check a common desktop-sized view |
| Wide desktop example | 1680 | 876 | Reproduce the dimensions shown in the product example |
For responsive testing, choose widths around the breakpoints in your own CSS. A screenshot at one width cannot show every intermediate layout; capture at each important breakpoint and, if a layout changes abruptly, just above and below it.
2. Make a viewport screenshot request
Replace YOUR_API_KEY with your ScreenshotAPI.net token and set url to the page to render. URL-encode the target URL in a query string so its own parameters do not become parameters of the screenshot request.
cURL
curl -G "https://shot.screenshotapi.net/v3/screenshot" \
--data-urlencode "token=YOUR_API_KEY" \
--data-urlencode "url=https://example.com/pricing" \
--data-urlencode "width=1440" \
--data-urlencode "height=900" \
--data-urlencode "file_type=png" \
-o screenshot.pngThe -G option sends the supplied values as query parameters, and -o writes the binary image response to a file. Use a different output extension if you change file_type.
Python
import requests
endpoint = "https://shot.screenshotapi.net/v3/screenshot"
params = {
"token": "YOUR_API_KEY",
"url": "https://example.com/pricing",
"width": 1440,
"height": 900,
"file_type": "png",
}
response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
image_file.write(response.content)Install the dependency with python -m pip install requests. raise_for_status() surfaces HTTP failures instead of saving an error response under an image filename.
Node.js
const params = new URLSearchParams({
token: 'YOUR_API_KEY',
url: 'https://example.com/pricing',
width: '1440',
height: '900',
file_type: 'png',
});
const response = await fetch(
`https://shot.screenshotapi.net/v3/screenshot?${params}`
);
if (!response.ok) {
throw new Error(`Screenshot request failed: ${response.status} ${await response.text()}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import('node:fs/promises').then(({ writeFile }) =>
writeFile('screenshot.png', image)
);Save as an ES module file and run with a Node.js version that provides the global fetch API. Keep the token in an environment variable or secret store in production rather than committing it to source control.
3. Understand viewport, full-page, and clip
These settings address different capture needs:
| Goal | Setting or method | What it controls |
|---|---|---|
| Render at a chosen browser-window size | width and height |
The viewport dimensions before capture |
| Capture the entire scrollable document | Full-page option | The captured page extent beyond the first viewport |
| Capture a rectangle within the page | clip with x, y, width, and height |
The crop coordinates and dimensions |
A viewport screenshot normally shows the visible browser area at the requested size. Full-page capture extends the result to include the scrollable page. ScreenshotAPI.net’s feature overview describes its full-page option as full_page=true; consult the documentation for the exact options supported by the API version you use. The element screenshot documentation describes clip as a rectangle specified with x, y, width, and height. A clip is a crop, not another way to set the browser viewport.
For a full-page capture, keep the desired viewport width and height and enable the documented full-page option. For a cropped region, use the clip coordinates and dimensions documented for your endpoint. Don’t assume clip coordinates will change responsive layout: set the viewport separately when the rendered layout itself matters.
4. Use per-row dimensions in bulk captures
ScreenshotAPI.net’s bulk documentation says CSV rows may include optional width and height inputs for viewport customization. Include the desired dimensions on each row when different URLs need different layouts, and verify the current bulk CSV schema in the official documentation before generating a large batch. Bulk screenshot documentation.
5. Validate the resulting capture
- Confirm the saved file is an image rather than an API error body. Open it or inspect the response status and content type.
- Check the rendered layout at the intended width, especially navigation, columns, and breakpoint-specific elements.
- Compare the image bounds with what you asked for. Full-page capture can produce an image taller than the viewport.
- If text or layout differs from a local browser, check whether the page finished loading and whether it depends on a login, cookie, or location-specific state.
- For repeatable comparisons, keep the target URL, viewport, capture options, and page state consistent between requests.
6. Troubleshoot common problems
| Symptom | Likely cause | What to check |
|---|---|---|
| The page looks like the wrong device layout | The requested width does not match the breakpoint you meant to test, or the parameters were omitted or misspelled. | Check the final request URL for integer width and height values, then compare the width with your CSS media queries. |
| The capture is only the first screen | Viewport capture was requested, but full-page capture was expected. | Enable the full-page option supported by your endpoint. Width and height alone set the viewport; they do not mean “capture the whole document.” |
| The image is unexpectedly cropped | A clip or output operation is limiting the captured area. | Review any crop or clip parameters and distinguish them from viewport width and height. |
| The result is an error page or cannot be opened | The request may have returned an HTTP error or a text error body that was saved with an image extension. | Check the HTTP status and response body before writing the file. In Python, call raise_for_status(); in Node.js, check response.ok. |
| The URL loads but its layout is incomplete | Client-side rendering, delayed content, or a page-specific load requirement may not have finished. | Check the service’s current wait and rendering options for your endpoint, and verify that the target URL is publicly reachable in the capture context. |
| A URL containing query parameters is captured incorrectly | The inner URL was not encoded as one query parameter. | Use cURL’s --data-urlencode, Python’s params argument, or JavaScript’s URLSearchParams. |
| A batch uses the same size for every page | Per-row dimensions may be missing or the CSV columns may not match the documented schema. | Check the bulk documentation’s current width and height fields and inspect a small batch first. |
7. Performance, reliability, and cost considerations
A larger viewport means more page area for the browser to lay out and may change responsive behavior; full-page capture can require rendering more content than a viewport capture. The actual time and response size depend on the target page and the capture options. Keep dimensions only as large as the use case needs, and use a viewport capture when below-the-fold content is irrelevant.
For production jobs, set a request timeout appropriate to your workload, check status before treating the body as an image, and retry only transient failures with a bounded retry policy. Avoid logging API tokens. For bulk work, validate dimensions and output on a small sample before processing the full input. The research material does not establish current ScreenshotAPI.net pricing or service guarantees, so check its current account terms for cost and quota details.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. One request sets a viewport with width and height; see the ScreenshotNeo API documentation for its options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-d width=1440 \
-d height=900 \
-o shot.webpCookie banners are accepted like a visitor and removed along with known consent platforms, newsletter popups, and chat widgets before the shot; each of those steps can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers identify 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 screenshots.
Sign up free for 1,000 screenshots a month, with no card required.
FAQ
Do width and height mean the output image will always have those exact pixel dimensions?
They set the browser viewport. Full-page capture or other output and crop behavior can affect the final image bounds.
Can I use width and height for a mobile-style screenshot?
Yes. Use dimensions appropriate to the narrow layout you need to render, such as the dossier’s 390×844 example, and remember that responsive behavior is driven by the page’s own breakpoints.
Should I use clip instead of width and height?
Use width and height to control the browser window used for layout. Use clip when you need a rectangular crop of the rendered page.
Can different URLs in a bulk request have different viewport sizes?
The bulk documentation says CSV rows can include optional width and height values. Confirm the current schema and use per-row fields for different dimensions.
Sources
- ScreenshotAPI.net product page — endpoint example and viewport dimensions.
- ScreenshotAPI.net Playground — viewport and full-page settings.
- Bulk screenshot documentation — per-row width and height inputs.
- Element screenshot documentation — clip rectangle behavior.
