How to Set the Device Scale Factor in a Screenshot API Request
Set device scale factor at the browser emulation layer, then choose whether screenshots use CSS or device pixels. The exact request field depends on your API.
There is no universal screenshot API parameter for device scale factor. With Chrome DevTools Protocol (CDP), set deviceScaleFactor using Page.setDeviceMetricsOverride before capturing. With Playwright, configure deviceScaleFactor on the browser context, then choose the screenshot output mapping with scale: "css" or scale: "device". A hosted screenshot API may use different field names and defaults, so check that provider’s documentation.
What device scale factor changes
A device scale factor (often called device pixel ratio) relates the emulated device’s physical pixels to CSS pixels. It affects device emulation and can affect how many pixels a screenshot contains. It is separate from the page’s CSS viewport dimensions: a 1280-pixel-wide CSS viewport at a scale factor of 2 can produce an image 2560 pixels wide when output is captured at device scale.
Keep these two decisions separate:
- Emulated device scale: the browser’s device pixel ratio and related rendering behavior.
- Screenshot output scale: whether the resulting file maps one output pixel to each CSS pixel or each device pixel.
Set the factor with Chrome DevTools Protocol
Call Page.setDeviceMetricsOverride on the page target before Page.captureScreenshot. Supply the required width, height, and mobile fields along with deviceScaleFactor.
await client.send("Page.setDeviceMetricsOverride", {
width: 1280,
height: 800,
deviceScaleFactor: 2,
mobile: false
});
const result = await client.send("Page.captureScreenshot", {
format: "png"
});This is the CDP method-level example; the exact client creation and target/session setup depends on the library connecting to Chrome. The protocol defines deviceScaleFactor as a number, and setting it to 0 disables the override. The metrics override also changes emulated screen dimensions and related CSS media query results. See the [CDP Page domain reference](https://chromedevtools.github.io/devtools-protocol/tot/Page/#method-setDeviceMetricsOverride).
Choose dimensions and mobile behavior deliberately
widthandheightdescribe the emulated device metrics in CSS pixels.mobilecontrols mobile-style emulation behavior; it is not implied merely by selecting a high scale factor.- Use a positive factor such as
2for a specific emulated density, or0to disable the override.
Set the override on the same target and session that you use for the screenshot. If your automation framework creates a new page or context, apply the setting there before capture.
Playwright: context density and screenshot scale
Playwright has two related but distinct settings. Set deviceScaleFactor when creating the browser context to emulate density. Set the screenshot option scale to choose output pixel mapping.
import { chromium } from "playwright";
const browser = await chromium.launch();
const context = await browser.newContext({
viewport: { width: 1280, height: 800 },
deviceScaleFactor: 2
});
const page = await context.newPage();
await page.goto("https://example.com", { waitUntil: "networkidle" });
// One output pixel per CSS pixel.
await page.screenshot({ path: "page-css.png", scale: "css" });
// One output pixel per device pixel; this can produce a larger image.
await page.screenshot({ path: "page-device.png", scale: "device" });
await browser.close();Use scale: "css" when the output should be one pixel per CSS pixel. Use scale: "device" when the output should preserve device-pixel resolution. Confirm the options for the Playwright API surface and version you use; defaults can vary between APIs. See [Playwright screenshot options](https://playwright.dev/docs/api/class-page#page-screenshot) and [browser context options](https://playwright.dev/docs/api/class-browser#browser-new-context-option-device-scale-factor).
Puppeteer: configure emulation separately from capture
Do not assume deviceScaleFactor belongs in Puppeteer’s screenshot options. The documented screenshot options cover capture behavior such as full-page output, clipping, image format, and quality. Configure device emulation through the relevant page or browser API, then call the screenshot method.
import puppeteer from "puppeteer";
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.setViewport({
width: 1280,
height: 800,
deviceScaleFactor: 2
});
await page.goto("https://example.com", { waitUntil: "networkidle0" });
await page.screenshot({ path: "page.png", fullPage: true });
await browser.close();Check the Puppeteer version’s viewport and screenshot references if your installed API differs. The key is to set emulation on the page before capture, rather than adding an unrecognized screenshot option. See [Puppeteer Page.setViewport](https://pptr.dev/api/puppeteer.page.setviewport) and [ScreenshotOptions](https://pptr.dev/api/puppeteer.screenshotoptions).
Hosted screenshot APIs: verify the provider’s parameter
A hosted API may expose a device scale, device pixel ratio, retina, or output-image scale option—or may not expose one. Do not send deviceScaleFactor simply because CDP or Playwright uses that name. Check the provider’s documentation for the exact field, accepted values, and whether it controls emulation, output dimensions, or both.
When evaluating an API request, verify:
- The viewport width and height and whether they are CSS pixels.
- The documented scale or density field and its default.
- Whether the field changes page rendering, output pixel dimensions, or both.
- Whether the provider supports a specific device preset that overrides custom dimensions.
- The returned image dimensions and format, especially if downstream code expects fixed pixel sizes.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its scale option controls retina scale; use the documented request options and examples in the ScreenshotNeo API documentation. A one-call request looks like this:
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://stripe.com \
-o shot.webpCookie banners are accepted and removed before capture, along with known newsletter popups and chat widgets. Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing; response headers identify the page verdict and billing status. An MCP server lets AI agents use screenshot tools. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots. Sign up for the free plan.
Choosing the right output
| Need | Configuration to check | Trade-off |
|---|---|---|
| Predictable CSS layout dimensions | Capture at CSS scale where supported | Fewer output pixels than a high-density capture |
| High-density visual detail | Emulate the desired device scale and capture at device scale | Potentially larger image dimensions and files |
| Consistent output for a device class | Set viewport, device scale, and mobile behavior together | More emulation settings to keep aligned |
| Hosted capture without browser maintenance | Use the provider’s documented scale option | Field names and semantics are provider-specific |
Troubleshooting
The image dimensions did not change
Check whether you changed the emulated device scale or only a screenshot output option. In Playwright, context deviceScaleFactor and screenshot scale have different roles. Also verify that the context or CDP override was applied to the page being captured.
The API rejects the scale parameter
The provider may use a different field name, accept only preset values, or not support density control. Consult its API reference and remove fields that are not documented for that endpoint.
The screenshot is larger than expected
A device-scale output can contain more pixels than a CSS-scale output. Check the viewport and device scale together, and choose CSS output mapping when one image pixel per CSS pixel is the desired result.
Mobile CSS or media queries changed unexpectedly
CDP’s metrics override affects emulated screen dimensions and related CSS media query results. Review width, height, and the mobile value as well as the device scale factor.
The setting appears to have no effect in Puppeteer
deviceScaleFactor is not a screenshot option in the documented screenshot options reference. Apply emulation through the page or viewport API before capturing, and confirm the installed Puppeteer version’s method signature.
Performance, reliability, and cost
Higher-density output can mean more image pixels and a larger file, so account for the extra transfer, storage, and processing in downstream systems. The actual size depends on the captured page, format, and provider; no single multiplier or timing applies to every screenshot API. If consumers require fixed dimensions, validate the returned image size rather than assuming that the viewport alone determines it.
For repeatable captures, explicitly set viewport and scale-related options instead of relying on defaults. Pin the browser automation version where practical, and verify provider-specific behavior when switching APIs. For hosted services, include image format and any documented cache behavior in cost and freshness decisions; do not infer billing or caching rules from the scale setting.
FAQ
Is device scale factor the same as screenshot scale?
No. Device scale factor configures emulated device density; a screenshot scale option determines how CSS or device pixels map to output pixels.
What does a CDP device scale factor of zero mean?
In Page.setDeviceMetricsOverride, zero disables the device scale override.
Can I assume a hosted API accepts deviceScaleFactor?
No. Use the field name and semantics documented by that specific provider.
Does a higher scale factor improve layout responsiveness?
It changes density emulation, not the CSS viewport width by itself. Set the viewport dimensions and mobile behavior for the layout you need to reproduce.
