How to Set a Custom Viewport Width and Height in a Screenshot API

Set both dimensions explicitly in the format required by your screenshot API. For example, Screenshot API accepts a JSON viewport object in a POST request, while its GET format uses width and height query parameters. These names and behaviors are provider-specific: verify units, accepted ranges, defaults, and full-page options in the API’s documentation.

For Screenshot API, this POST request asks for a 1280 × 720 CSS-pixel viewport and a PNG response:

curl -X POST "https://api.screenshot-api.org/api/v1/screenshot" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","viewport":{"width":1280,"height":720},"format":"png"}'

Keep API keys out of published code and source control. Screenshot API recommends sending the key in an authorization header where supported.

1. What viewport width and height control

Viewport width and height describe the browser’s visible rendering area, usually in CSS pixels. They influence responsive breakpoints and layout: a page rendered at 390 pixels wide may show a mobile navigation menu, while the same page at 1280 pixels may show a desktop layout.

They do not necessarily determine the output file’s physical pixel dimensions. A separate device-scale or output-scale setting may multiply the image resolution while keeping the same CSS layout viewport. For example, a 1280 × 720 CSS-pixel viewport captured at a scale factor of 2 can produce an image with more output pixels without making the page lay out as though the viewport were 2560 pixels wide.

2. Set dimensions for the API you use

First check whether the API expects a viewport object or separate width and height fields. Even one provider can accept different shapes for GET and POST requests.

Screenshot API: POST JSON

Its documented POST request places the dimensions inside viewport. This example uses a placeholder token and a 1440 × 900 viewport:

curl -X POST "https://api.screenshot-api.org/api/v1/screenshot" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","viewport":{"width":1440,"height":900},"format":"png"}'

Reference: Screenshot API documentation. Confirm the current endpoint, response handling, and supported fields in the provider’s reference before integrating.

Screenshot API: GET parameters

The GET form uses separate width and height query parameters. The exact way the API expects authentication and the response to be handled should be checked in its documentation.

curl -G "https://api.screenshot-api.org/api/v1/screenshot" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "width=1440" \
  --data-urlencode "height=900" \
  --data-urlencode "format=png" \
  --data-urlencode "access_key=YOUR_API_KEY" \
  -o screenshot.png

Do not assume the POST authentication method and the GET authentication method are interchangeable; use the provider’s documented method.

Python example

This runnable example submits the documented POST shape and saves the response. Replace the placeholder key and check the provider’s response format and error handling for your use case.

import requests

url = "https://api.screenshot-api.org/api/v1/screenshot"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "url": "https://example.com",
    "viewport": {"width": 1440, "height": 900},
    "format": "png",
}

response = requests.post(url, headers=headers, json=payload, timeout=90)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
    image_file.write(response.content)

Node.js example

With Node.js 18 or later, use the built-in fetch and save the returned bytes:

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

const response = await fetch("https://api.screenshot-api.org/api/v1/screenshot", {
  method: "POST",
  headers: {
    Authorization: "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    viewport: { width: 1440, height: 900 },
    format: "png",
  }),
  signal: AbortSignal.timeout(90_000),
});

if (!response.ok) {
  throw new Error(`Screenshot request failed: ${response.status} ${await response.text()}`);
}

await writeFile("screenshot.png", Buffer.from(await response.arrayBuffer()));

3. Choose dimensions for your capture

Decide which layout you need to reproduce. Use the CSS viewport width that activates the target responsive breakpoint. Use the height needed for the visible composition.
Set both values explicitly. This avoids relying on undocumented or changing defaults.
Check units and limits. Providers may define CSS pixels, device pixels, a minimum or maximum dimension, or special values.
Decide whether you need a viewport shot or a full-page shot. A viewport height sets the visible browser area; it does not automatically request the entire scrollable document.
Set output density separately if needed. Look for a device scale factor or output scale option instead of increasing viewport width to make a sharper image.
Save the exact request configuration. Keeping the URL, dimensions, scale, and relevant options together helps reproduce a capture later.

4. Provider field names and behavior vary

Do not copy one provider’s parameter names or limits into another service’s request. These examples from the research dossier show why it is important to check each provider’s reference:

Provider	Documented dimension shape	Relevant distinction
Screenshot API	POST `viewport.width` and `viewport.height`; GET `width` and `height`	Documents separate full-page and device-scale options. Reference.
ScreenshotAPI	`viewportWidth` and `viewportHeight`	Documents defaults of 1280 × 720, a full-page option, and output scaling. Reference.
ScreenshotEngine	`width` and `height` for GET or POST	Documents GET width from 100 to 3840 and height from 100 to 10000 or `full`. Its viewport presets do not emulate every physical-device behavior. Reference.
Cloudflare Browser Rendering	A `viewport` object with width and height	Lists device scale and mobile-oriented flags separately. Reference.

Provider documentation and options can change. Confirm the live reference for the service you choose, especially if your integration depends on a specific default or validation range.

5. Viewport capture, full page, and device emulation

Viewport capture versus full page

A normal screenshot generally captures the visible browser viewport. A full-page flag, when supported, asks the service to capture beyond the initial viewport. A tall viewport and a full-page capture are separate concepts: setting height to 5000 does not guarantee that the API will capture the whole document.

Full-page behavior can also interact with sticky headers, fixed elements, lazy-loaded content, and very long documents. Check whether the provider scrolls the page to load content, stitches sections, or applies a maximum output size. The research dossier does not establish one universal behavior.

Pixel density and output scaling

Keep layout size and output scale separate. Set width and height to control responsive rendering; use the provider’s scale option when you need a higher-density output. Larger output images take more bandwidth and storage and may take longer to process.

Custom dimensions versus a device preset

A width and height can reproduce a viewport size without reproducing a physical device. Touch input, user agent, browser behavior, and pixel density may need separate options. Cloudflare exposes mobile, touch, landscape, and device-scale options in addition to viewport dimensions. ScreenshotEngine notes that its presets do not emulate browser, touch input, user agent, or pixel density.

6. Troubleshooting

Symptom	Likely cause	What to check
The layout looks like the wrong breakpoint	The API ignored the dimensions, expects different field names, or received values in a different unit.	Check the request schema and response, send both dimensions explicitly, and verify that the width is the CSS viewport width you intend.
The image is sharper or larger, but the layout did not change	You changed output scale or device scale instead of the viewport width.	Set viewport width and height directly; configure pixel density separately.
The image stops at the visible area	The request did not enable the provider’s full-page option.	Use the documented full-page field and check any maximum page or image size.
The request fails validation	A dimension is missing, non-numeric, outside the service’s range, or formatted incorrectly.	Send numeric width and height in the documented shape and check provider-specific limits.
A mobile preset still behaves differently from a phone	Viewport dimensions alone do not necessarily emulate touch, user agent, or device scale.	Configure those controls separately if the API supports them, and confirm what the preset actually changes.
The capture is inconsistent across runs	Content may load asynchronously or depend on network timing, cookies, or other request state.	Use documented wait controls if available and keep viewport, scale, URL, and relevant state consistent.

7. Performance, reliability, and cost

For repeatable captures, make dimensions explicit and keep the rest of the capture configuration stable. Larger viewports and high-density output can produce larger images; full-page captures can involve more content than viewport captures. The exact effects on processing time, limits, and price depend on the provider. The research dossier does not establish comparable performance benchmarks or a universal cost model, so consult the service’s current pricing and limits.

For production use, handle non-success HTTP responses, set a request timeout appropriate to your workflow, and avoid treating every response body as an image without checking the status and response type. When a capture must be reproducible, record the requested viewport and scale alongside the saved artifact.

8. Or skip the browser setup

If you want to request a screenshot without managing browser setup, ScreenshotNeo accepts width and height parameters on its screenshot API. The parameters used by other screenshot APIs also work, which makes switching easier. See the ScreenshotNeo API documentation for supported options and current request details.

cURL

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

Python

import requests

r = requests.get("https://api.screenshotneo.com/v1/shot", params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com", "width": 1280, "height": 720}, 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://stripe.com', width: '1280', height: '720' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`Screenshot request failed: ${res.status}`);
await import('node:fs/promises').then(({ writeFile }) => writeFile('shot.webp', Buffer.from(await res.arrayBuffer())));

With ScreenshotNeo, cookie banners, popups, and chat widgets are removed before the shot; bot checks, blank pages, and failed loads are never billed; and an 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. The same features are available on every plan.

9. FAQ

Should I use the viewport dimensions of my laptop or the screenshot’s desired pixel dimensions?

Use the CSS viewport dimensions that produce the layout you want. Set output scale separately if you need more image pixels.

Does setting a very large height capture the full page?

Not necessarily. Use the provider’s full-page option when available and check its limits and behavior.

Can the same width and height reproduce a specific phone?

They can reproduce a viewport size, but they may not reproduce touch behavior, user agent, browser characteristics, or pixel density. Those may require separate device-emulation controls.

Are width and height always measured in CSS pixels?

No universal unit applies across APIs. Check the selected provider’s documentation for units and validation rules.