GrabzIt Screenshot API: Set Viewport Size and Device Scale
Set GrabzIt’s browser viewport separately from output image size, and learn what its high-definition option does—and does not—control.
Set the rendered browser size with GrabzIt’s browser width and height parameters: bwidth and bheight in the JavaScript API, or browserWidth and browserHeight in its Node.js client. Set output image dimensions separately with width and height. For GrabzIt’s documented high-definition mode, set hd=1; its parameter reference says this doubles image dimensions. The reviewed documentation does not define a separate device-scale-factor or device-pixel-ratio option.
This distinction matters for responsive pages: changing the output image size does not change the browser viewport used to render the page. The viewport determines which layout the site presents; output dimensions determine the dimensions of the resulting image or thumbnail.
1. Choose the setting that matches your goal
| Goal | Setting | Effect |
|---|---|---|
| Render a particular responsive layout | bwidth, bheight (Node.js: browserWidth, browserHeight) |
Sets the browser window used for rendering. |
| Resize the resulting image | width, height |
Sets output image dimensions; it does not select a different responsive viewport. |
| Request higher-definition output | hd=1 |
GrabzIt documents this mode as doubling image dimensions. hd=0 is standard definition. |
| Ask for a mobile version of a page | requestas=1 with a mobile bwidth |
Requests the mobile version where the site provides one. |
GrabzIt documents JavaScript API defaults of 1366 × 1170 pixels for browser width and height, with a maximum of 10000 pixels for each. Its Node.js reference lists the corresponding browserWidth and browserHeight options with the same defaults and maximums. See the JavaScript API parameter reference and Node.js technical documentation.
2. Set viewport dimensions in the JavaScript API
Pass the browser dimensions when configuring the capture. The following shows the relevant parameter names and values; use them with the capture flow from the JavaScript API documentation for your project.
var params = new GrabzItImageOptions();
params.browserWidth = 1440;
params.browserHeight = 1000;
// Output size is separate from the rendered browser viewport.
params.width = 1200;
params.height = 800;
// Set to true when you want GrabzIt's documented HD mode.
params.hd = true;In the JavaScript API parameter interface, the corresponding HTTP parameter names are bwidth, bheight, width, height and hd. Consult the parameter reference for the complete capture method and current option signatures.
3. Set viewport dimensions with the Node.js client
For the Node.js client, use browserWidth and browserHeight for the rendering viewport. Image width and height describe output size. This example shows the option names to add to the client’s screenshot options object; initialize the client and submit the capture using the workflow documented for your installed package version.
const options = {
browserWidth: 1440,
browserHeight: 1000,
width: 1200,
height: 800
};The reviewed Node.js reference documents the browser options and limits. The cited reference does not establish a Node.js deviceScaleFactor setting. Check the Node.js technical documentation for package setup, capture submission and returned-file handling.
4. Use GrabzIt’s REST API
GrabzIt’s REST guide uses a GET request for URL captures and URL-encoded form data for HTML capture. The request below illustrates a URL capture with viewport dimensions and HD mode as query parameters. Supply your application key on a server, and avoid exposing it in browser-side REST calls. GrabzIt recommends its JavaScript API for client-side use.
curl -G 'https://api.grabz.it/services/convert' \
--data-urlencode 'key=YOUR_APPLICATION_KEY' \
--data-urlencode 'url=https://example.com' \
--data-urlencode 'format=png' \
--data-urlencode 'bwidth=1440' \
--data-urlencode 'bheight=1000' \
--data-urlencode 'hd=1'Use the exact REST endpoint and required parameters documented for your account and API version. The example focuses on the viewport and resolution parameters rather than assuming a response format or download workflow. The official REST guide describes request handling and credential precautions.
5. Request a mobile rendering
Set requestas=1 to request the mobile version, and pair it with a standard mobile browser width using bwidth. This asks for a mobile variant; it does not guarantee a distinct layout because some sites do not provide a special mobile version. GrabzIt also suggests using a smaller PDF page size when capturing to PDF for a more authentic mobile screenshot. See GrabzIt’s JavaScript parameter reference and its guide to screenshotting mobile websites with JavaScript.
// REST parameter values for a mobile URL capture
bwidth=390
requestas=16. Get a higher-resolution result
Enable hd=1 for GrabzIt’s documented high-definition mode. The JavaScript parameter reference describes it as doubling image dimensions; use hd=0 for standard definition. This is the documented resolution control in the reviewed material. Do not assume it is equivalent to setting an independent browser device pixel ratio: the reviewed references do not document a separate device-scale-factor option.
If the page itself must render at a different responsive breakpoint, change bwidth and, where needed, bheight. If the rendered layout is already right and the image should have different output dimensions, adjust width/height or use HD mode according to the output requirement.
7. A decision checklist
- Choose the target layout first; set browser width and height to control the render viewport.
- Choose output dimensions independently; do not use output width as a substitute for viewport width.
- Use
hd=1when GrabzIt’s documented doubled-dimension HD output matches the need. - For mobile, combine
requestas=1with a mobile browser width, then account for sites that have no special mobile version. - Keep application credentials on your server when calling REST.
8. Troubleshooting
| Symptom | Likely cause | What to change |
|---|---|---|
| The page still shows a desktop layout after changing image width. | Output width changes the resulting image dimensions, not the browser viewport. |
Set bwidth (or Node.js browserWidth) to the intended responsive width. |
| The capture is not the expected height. | The browser viewport height and output image height are separate settings. | Set bheight for the render window; set output height only for the resulting image size. |
| A mobile request looks like desktop. | The site may not offer a special mobile version, or the capture width may not be appropriate. | Use requestas=1 with a standard mobile bwidth; verify whether the target site serves a distinct mobile experience. |
| Code rejects a device-scale option. | The reviewed GrabzIt documentation does not identify a general-purpose device scale factor parameter. | Use the documented hd option for doubled image dimensions, or set viewport and output size separately. |
| A browser-side REST request exposes a key. | REST calls can reveal application credentials sent from client code. | Move the REST request to a server, or use GrabzIt’s JavaScript API for client-side use as its guide recommends. |
| A requested dimension is rejected or not honored. | Browser dimensions exceed the documented maximum, or the option name does not match the API interface. | Keep each browser dimension at or below 10000; use bwidth/bheight for JavaScript parameters and browserWidth/browserHeight in Node.js. |
9. Reliability, performance and cost considerations
The dossier’s official references establish parameter defaults, limits and documented HD behavior, but provide no benchmark, latency guarantee or cost figures for these settings. Larger browser viewports and high-definition output can mean more pixels to render or transfer as a practical consequence, so request only the dimensions your downstream use needs. For repeatable captures, record viewport dimensions, output dimensions, format and HD mode alongside each job so comparisons use the same settings.
Stay within the documented 10000-pixel maximum for each browser dimension. If a site has no mobile-specific version, requesting the mobile variant may not change its layout. For REST usage, protect the application key and follow the documented request method for the capture type.
10. Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. It returns a screenshot or PDF from one GET request; see the API documentation for available options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpScreenshotNeo removes cookie banners, newsletter popups and chat widgets before capture. Bot checks, blank pages and failed loads are never billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000. Sign up for 1,000 free screenshots a month, with no card required.
FAQ
Does GrabzIt support a deviceScaleFactor option?
No separate device-scale-factor option is established by the reviewed documentation. GrabzIt documents hd=1 as a high-definition mode that doubles image dimensions.
What are the default GrabzIt browser dimensions?
The JavaScript and Node.js references list defaults of 1366 pixels wide by 1170 pixels high, with a maximum of 10000 pixels for each dimension.
Does setting a mobile request guarantee a mobile layout?
No. requestas=1 requests a mobile version, but some sites do not have a distinct mobile version.
