How to set viewport width and height in a ScreenshotOne request
Set ScreenshotOne’s viewport with pixel dimensions, understand device presets and full-page behavior, and avoid confusing viewport size with output image size.
Set the ScreenshotOne request parameters viewport_width and viewport_height to pixel values. For example, use 1440 by 900 for a desktop-sized browser viewport. The documented defaults are 1280 by 1024.
These values control the browser viewport and therefore the responsive layout being rendered. They do not resize the output image; use image_width and image_height for that. See ScreenshotOne’s options reference for the supported request parameters.
1. Set custom viewport dimensions
Add both parameters to a /take request. This complete cURL example captures a page at 1440 × 900 pixels:
curl -G 'https://api.screenshotone.com/take' \
--data-urlencode 'url=https://example.com' \
--data-urlencode 'viewport_width=1440' \
--data-urlencode 'viewport_height=900' \
--data-urlencode 'access_key=YOUR_ACCESS_KEY' \
-o screenshot.pngReplace YOUR_ACCESS_KEY with your key and use the target page in place of https://example.com. Keep the key private: avoid publishing it in client-side code or public repositories. Build query strings with a URL or query-parameter library so the target URL and credentials are encoded correctly.
Python SDK
The ScreenshotOne Python SDK exposes matching builder methods, viewport_width() and viewport_height(). The following uses the documented builder calls; add them to the SDK’s normal capture flow:
import screenshotone
client = screenshotone.Client(access_key="YOUR_ACCESS_KEY")
request = screenshotone.TakeOptions("https://example.com")
request.viewport_width(1440)
request.viewport_height(900)
response = client.take(request)
with open("screenshot.png", "wb") as output:
output.write(response.content)Consult the Python SDK documentation for the current package setup and response handling.
What the dimensions affect
- Width: sets the horizontal browser viewport. It can change responsive breakpoints and whether navigation, sidebars, or columns appear.
- Height: sets the vertical browser viewport for an ordinary viewport capture. Its role in full-page captures depends on the selected algorithm.
- Output dimensions:
image_widthandimage_heightresize the resulting image while preserving its aspect ratio; they do not set the browser layout viewport.
| Goal | Use | Example |
|---|---|---|
| Render a responsive layout at a specific browser size | viewport_width, viewport_height |
1440 × 900 |
| Constrain the resulting image dimensions | image_width, image_height |
Resize a capture for a thumbnail |
| Emulate a named device preset | viewport_device |
Choose a supported device name |
2. Choose custom dimensions or a device preset
Use explicit width and height when you need a particular viewport, such as a fixed screenshot size for a design review. Use viewport_device when you want a supported device preset to bundle viewport dimensions with emulation settings.
A device preset configures viewport_width, viewport_height, device_scale_factor, viewport_mobile, viewport_has_touch, and viewport_landscape. Explicit request values for individual settings, including width and height, can override the preset. Device emulation is not the same as using a physical device.
The supported device list can change. Retrieve the current list from the API rather than depending on an old example:
curl -G 'https://api.screenshotone.com/devices' \
--data-urlencode 'access_key=YOUR_ACCESS_KEY'For production use, query that endpoint with your language’s HTTP client and parse its response. Select a device name from the returned list, then pass it as viewport_device in the screenshot request.
3. Account for full-page capture behavior
For full-page screenshots, width still determines the responsive layout and the resulting page width. Height depends on the full-page algorithm:
- Default algorithm: the viewport height is temporarily stretched to match the page height, so the supplied
viewport_heightmatters less to the final full-page capture. by_sectionsalgorithm: the supplied height sets section size and scroll increments. Smaller sections mean more scroll events and may trigger more lazy-loaded content, but can take longer.
The full-page guide says capture_beyond_viewport=true is the default for full-page screenshots and is used to capture content beyond the initial viewport. See the full-page screenshot guide when choosing an algorithm and capture behavior.
If a page relies on lazy loading, choose dimensions and full-page behavior with that page in mind. A taller section can mean fewer scroll steps; a shorter section can expose more intermediate content to the capture process, at the cost of more work.
4. Verify the rendered layout
- Choose viewport dimensions that correspond to the layout you want to inspect.
- Set both
viewport_widthandviewport_heightexplicitly so the request does not rely on defaults. - Capture the page and inspect the output at its original size.
- If the layout is wrong, check whether the page has responsive breakpoints near your chosen width, and whether a device preset or other request option overrides your dimensions.
- If the browser layout is right but the file size or displayed image size is wrong, adjust output image options separately.
5. Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
| The page still looks like a mobile layout | The viewport width is below the site’s responsive breakpoint, or a mobile device preset is active. | Set a wider viewport_width. If using viewport_device, check its mobile settings and any explicit overrides. |
| The screenshot dimensions do not match the requested viewport | You are comparing output image size with browser viewport size, or the request uses a device scale factor. | Use viewport options to control layout and image resize options to control output size. Check the preset’s device_scale_factor when emulating a device. |
| The page width is correct but the full-page height differs | The default full-page algorithm stretches the viewport height to the page; height behavior also differs with by_sections. |
Choose the full-page algorithm based on whether you want page-length capture or controlled section-and-scroll sizing. |
| A parameter seems ignored | A device preset may supply the same setting, the parameter name may be misspelled, or a URL may have been assembled without proper encoding. | Use the exact names viewport_width and viewport_height, check preset overrides, and construct the query with a URL encoder. |
| Device preset is rejected | The device name may be stale because the supported list is dynamic. | Fetch GET https://api.screenshotone.com/devices with your access key and use a name in the current response. |
| Images or sections are missing in a full-page result | The page may lazy-load content as it scrolls, and the chosen algorithm or section size may not trigger the needed loading steps. | Try by_sections with an appropriate viewport height and inspect whether additional scroll steps capture the missing content. |
6. Performance, reliability, and cost
Viewport dimensions change what the browser renders; they are not a guarantee of a particular screenshot file size or capture duration. Larger full-page captures contain more page area. With by_sections, smaller heights create more scroll events and may take longer, while also giving lazy content more opportunities to load.
For repeatable results, specify both dimensions, use a stable target URL, and be explicit about device emulation when it matters. If you require a current device preset, fetch the supported list instead of hard-coding an old example. Treat full-page height separately from viewport height when interpreting a result.
7. Or skip the browser setup
If your goal is a screenshot rather than managing a browser capture service, ScreenshotNeo accepts a URL in one API call and returns an image or PDF. Its viewport options let you set a custom viewport, use device presets, and capture full pages. 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 viewport_width=1440 \
-d viewport_height=900 \
-o shot.webpScreenshotNeo removes cookie banners, popups, and chat widgets before the shot. Bot checks, blank pages, and failed loads are never billed, and response headers report the page verdict and billing status. Its MCP server lets AI agents take screenshots. 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, no card required.
Frequently asked questions
What are the default ScreenshotOne viewport dimensions?
The documented defaults are 1280 pixels wide and 1024 pixels high.
Can I set only the width?
You can pass the width parameter independently, but setting both dimensions explicitly makes the intended viewport clear and avoids relying on a default height.
Does viewport width change the full-page screenshot width?
Yes. The full-page guide says width determines the responsive layout and directly affects the full-page screenshot width.
Does a device preset lock the viewport dimensions?
No. A preset supplies dimensions and other emulation settings, but explicit individual request values can override them.
