How to set the viewport size in a URL2PNG screenshot

Set the URL2PNG v6 viewport parameter to the desired browser width and height in pixels, written as WIDTHxHEIGHT. For example, use viewport=1280x800. Add it to the complete query parameters before generating the request token, because the token is derived from the query string and your secret. URL2PNG’s quickstart guide documents the parameter and signing workflow.

1. Choose the viewport dimensions

The viewport is the browser’s visible layout area for the capture. Pick the width and height that match the layout you need, in pixels. The format uses a lowercase x, with width first:

viewport=1280x800

Use an explicit value rather than relying on an implicit default. URL2PNG’s documentation lists 1480x1037 in its advanced-options list, while an embedded Python helper uses 1280x1024; the documentation does not resolve that discrepancy.

2. Add the option to the URL2PNG request

A v6 request has this general shape:

https://api.url2png.com/v6/{APIKEY}/{TOKEN}/png/?url={ENCODED_TARGET}&viewport=1280x800

This is a schematic URL, not a ready-to-use signed request. Replace the placeholders with your account key, an encoded target URL, and a token generated for the full query and secret according to URL2PNG’s instructions. Do not reuse a sample token.

Signing order matters

Build the query parameters, including url, viewport, and any other options.
Serialize and encode the query using URL2PNG’s language-specific procedure.
Generate the token from the complete query string and your secret, as URL2PNG documents.
Construct the request URL and fetch the image.

If you change the viewport or any other parameter after signing, generate the token again. The signature corresponds to the request parameters, so changing the query can invalidate it.

3. Keep viewport, full-page capture, and scaling separate

Setting	What it controls	When to use it
`viewport`	The browser viewport width and height, in pixels	To control the responsive layout and visible capture dimensions
`fullpage`	Whether URL2PNG attempts to capture the whole document canvas	Set `true` when you want the page beyond the initial viewport; the documented default is `false`
`thumbnail_max_width`	A maximum width for the returned thumbnail	To constrain output image width; this is separate from browser layout dimensions

For example, a request can specify viewport=1280x800 and fullpage=true. The viewport determines the browser dimensions; fullpage separately asks for the entire document canvas. Do not use thumbnail_max_width as a substitute for setting the viewport.

4. Build the parameters in code

URL2PNG’s exact escaping, serialization, and token calculation must follow its official sample for your language. The following Python illustrates the important placement: include the explicit viewport in the parameters before encoding and signing them. It deliberately leaves the signature and HTTP request to the documented URL2PNG helper because those details depend on its prescribed signing implementation.

target_url = "https://example.com/page"
params = {
    "url": target_url,
    "viewport": "1280x800",
    "fullpage": "false",
}

# Next: use URL2PNG's official Python signing example to serialize
# these complete parameters, calculate the request token with your
# account secret, construct the v6 URL, and request the PNG.

Consult the official URL2PNG documentation for complete runnable signing examples. A fabricated token or guessed signature procedure would not produce a reliable example.

5. Cloudinary URL2PNG add-on syntax

If you use URL2PNG through Cloudinary’s add-on, the option goes in the add-on transformation path, for example:

/url2png/viewport=640x1136|fullpage=false

Cloudinary documents that these URLs generally need to be signed or eagerly generated by default, unless unsigned add-on transformations are enabled in account security settings. See Cloudinary’s URL2PNG add-on documentation for the integration’s URL and security details.

6. Troubleshooting

Symptom	Likely cause	What to check
The request is rejected after changing the viewport	The token was generated before the viewport was added or changed	Regenerate the token using the complete query string, including `viewport`
The captured layout does not match the desired device or breakpoint	The viewport value is missing, malformed, or reversed	Use width first, lowercase `x`, then height, such as `1280x800`
The image shows only the top part of a long page	Full-page capture was not requested	Add `fullpage=true`; viewport sizing alone does not ask for the whole document
The output is narrower than expected	Thumbnail scaling was confused with viewport dimensions	Check `thumbnail_max_width` separately from `viewport`
A Cloudinary add-on URL fails when requested directly	The transformation may require a signature or eager generation	Follow Cloudinary’s signing or eager-generation workflow, or check whether unsigned transformations are enabled

7. Performance, reliability, and cost considerations

The supplied URL2PNG documentation establishes the parameter syntax and signing behavior, but does not provide a benchmark, accepted dimension limits, or pricing information for this specific setting. Do not assume an undocumented maximum viewport size or infer that a larger viewport has a particular processing time or cost. Check the account and version-specific URL2PNG references for those details.

For repeatable captures, set the viewport explicitly, preserve the same complete parameter set when signing, and regenerate the signature whenever a parameter changes. Choose fullpage only when the entire document is needed, and use the thumbnail option only to control returned-image width.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. One GET request returns an image or PDF, with viewport and other capture options described in the API documentation. For a simple capture, here is the cURL call:

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

Cookie and consent banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing, and response headers report the page verdict and billing status. An 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.

FAQ

Does `viewport` mean the screenshot image’s final dimensions?

It sets the browser viewport used to render the page. URL2PNG documents thumbnail_max_width separately for constraining thumbnail output width.

Can I set a viewport and capture the full page?

Yes. Set the viewport dimensions and request fullpage=true as separate options.

Should I rely on URL2PNG’s default viewport?

For predictable results, specify the dimensions. The documentation page shows conflicting defaults in different sections.