How to Set Viewport Width and Height in Cloudinary Website Screenshots
Set a Cloudinary URL2PNG screenshot viewport with `viewport=WIDTHxHEIGHT`. Learn the URL format, signing requirements, common pitfalls, and alternatives.
Set the Cloudinary URL2PNG capture viewport with the option viewport=<width>x<height>. For example, viewport=1280x720 requests a 1280-pixel-wide by 720-pixel-high viewport. The width comes first. This controls the website capture viewport; resizing or cropping the resulting image is a separate, later Cloudinary transformation.
How the URL2PNG viewport option works
Cloudinary’s URL2PNG Website Screenshots add-on captures a public website through a dynamic Cloudinary transformation URL. You need to register for the add-on on your Cloudinary account. The delivery type is url2png; the target website URL is the public ID, followed by a second url2png segment containing options.
The general shape is:
https://res.cloudinary.com/<cloud_name>/image/url2png/<website-url>/url2png/viewport=<width>x<height>For a 1280 by 720 capture, the option is viewport=1280x720. The full delivery URL depends on your Cloudinary account, target public ID, and whether you use a signed URL or eager generation. Treat the pattern above as schematic: encode or construct the public ID and URL according to your Cloudinary setup rather than assuming every target can be pasted into the path unchanged.
Steps to set the capture dimensions
- Register for URL2PNG. Enable the URL2PNG Website Screenshots add-on for your Cloudinary account.
- Choose the intended viewport. Decide the width and height in pixels for the website’s capture request. For example, use 1440 by 900 for a wide desktop layout or 390 by 844 for a narrow mobile-sized layout.
- Set the delivery type and target. Use
url2pngdelivery and specify the public website URL as the target. - Append the options segment. Add
/url2png/viewport=WIDTHxHEIGHT, with width first and height second. - Handle URL access requirements. By default, URLs using this add-on must be signed or eagerly generated. Cloudinary also documents an account setting in Console Security to allow unsigned add-on transformations.
- Request the resulting asset. Cloudinary generates the screenshot, then caches and delivers it through its CDN.
Viewport dimensions versus output resizing
The viewport controls the dimensions of the website capture request. It can affect responsive layout: changing the width may cause a page to switch breakpoints, rearrange columns, or show a mobile navigation menu. The height defines the visible viewport height requested for capture.
Resizing or cropping the generated screenshot happens after capture as an image transformation. If you need a thumbnail, first request the desired website viewport, then apply Cloudinary’s image transformation to resize or crop the resulting screenshot. Do not use a thumbnail transformation as a substitute for choosing the capture viewport.
Important documentation example discrepancy
Cloudinary’s URL2PNG documentation prose describes a viewport of 640x1135, while the example URL immediately below it uses viewport=640x1136. That is a one-pixel height mismatch. The documented option name and width-by-height format are clear, but choose and state the height you actually intend to capture rather than copying both values as though they agree.
Options and practical choices
| Choice | What to do |
|---|---|
| Width and height | Write integer pixel dimensions as viewport=WIDTHxHEIGHT; width precedes height. |
| Responsive layout | Set the width to the layout you want the site to render. A narrow viewport may trigger the site’s mobile breakpoint. |
| Height | Set the height deliberately for the desired capture viewport; verify it rather than relying on the inconsistent documentation example. |
| Post-capture thumbnail | Apply a separate Cloudinary resize or crop transformation to the generated screenshot. |
| URL access | Use a signed URL or eager generation by default, or configure unsigned add-on transformations in Console Security if appropriate for the account. |
The cited add-on documentation establishes the viewport parameter and URL workflow; it does not establish additional viewport-specific behavior such as maximum dimensions or a universal default size. Check the current add-on details in your Cloudinary account for account-specific limits.
Troubleshooting
The transformation URL is rejected or does not return an image
Likely cause: URL2PNG is not enabled, or the transformation URL does not satisfy the account’s access rules. Fix: register for the add-on and use a signed URL or eager generation. If your account policy allows it, unsigned add-on transformations can be enabled in Console Security.
The captured page has the wrong responsive layout
Likely cause: the requested width is on the other side of a breakpoint from the layout you expected. Fix: adjust the width to the intended layout and request the screenshot again. Width is the first number in the viewport value.
The screenshot height is off by one pixel
Likely cause: the documentation prose and its example URL differ: 640x1135 versus 640x1136. Fix: explicitly choose the desired height and use that exact value in your URL.
The image is the right capture size but wrong delivery size
Likely cause: capture viewport and image resizing were treated as the same operation. Fix: set viewport for the website capture first, then apply a distinct image resize or crop transformation.
The requested website cannot be captured as expected
Confirm the target is a public website URL and that it is placed in the public ID portion of the URL2PNG transformation. The cited documentation does not specify handling for private, authenticated, or inaccessible pages, so do not assume those targets will behave like a public page.
Performance, reliability, and cost considerations
Cloudinary documents that URL2PNG screenshots are generated on demand through dynamic transformation URLs, then cached and delivered through Cloudinary’s CDN. Reusing a transformation URL can therefore use the cached delivered asset. The cited documentation does not provide a viewport-specific latency benchmark, cache duration, or add-on price, so check your Cloudinary account and current add-on terms for those details.
For repeatable output, keep the target URL, viewport dimensions, and any later resize transformation explicit. If a page changes over time, a cached screenshot may not reflect that change immediately; consult Cloudinary’s current cache controls for the behavior and invalidation options available to your account.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. A single GET request returns an image or PDF; it handles the capture infrastructure and offers options including viewport dimensions and full-page capture.
For example, request a 1280 by 720 screenshot with cURL:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-d viewport=1280x720 \
-o shot.webpSee the ScreenshotNeo API documentation for request options. Cookie banners, popups, and chat widgets are removed before the shot, with each cleanup step configurable. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed; response headers identify the page verdict and billing status. Its MCP server lets Claude, Cursor, and other MCP clients 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 for ScreenshotNeo’s free plan to get 1,000 screenshots a month with no card.
FAQ
What is the order of the viewport numbers?
Width first, then height: viewport=1280x720.
Does viewport set the final image’s dimensions?
It sets the website capture viewport. Resizing or cropping the generated image is a separate transformation.
Why does Cloudinary’s example show two heights?
The prose says 1135 pixels while the URL example says 1136 pixels. Choose the height you need and use it consistently.
Do URL2PNG transformations have to be signed?
They must be signed or eagerly generated by default. Cloudinary documents an option to allow unsigned add-on transformations through Console Security settings.
