CaptureKit screenshot dimensions are wrong: viewport and device scale fixes

If your CaptureKit screenshot dimensions are wrong, first separate the browser viewport from the final image size. CaptureKit documents viewport_width and viewport_height as viewport dimensions, with defaults of 1280 by 1024 pixels, and scale_factor as a separate high-resolution setting with a default of 1. full_page controls whether the capture extends beyond the visible viewport. Check the actual image’s pixel dimensions, then change one setting at a time. See the CaptureKit capture endpoint reference.

Understand which dimensions you are changing

A screenshot request involves several related but distinct sizes:

Setting or measurement	What it describes	What to check
`viewport_width`, `viewport_height`	The browser viewport dimensions in pixels, according to CaptureKit’s endpoint reference.	Use explicit values when you need a repeatable viewport. The documented defaults are 1280 × 1024.
`full_page`	Whether the capture includes the entire page rather than only what is visible in the viewport.	A full-page image may be taller than the viewport because content continues below the fold.
Device emulation	A selected device configuration used to emulate a device.	Record the selected device while debugging. Do not assume it is the same thing as setting viewport dimensions.
`scale_factor`	A separate scale setting for high-resolution screenshots. The documented default is 1.	Change it independently and inspect the resulting image’s pixel dimensions.
Image pixel dimensions	The width and height stored in the returned image file.	Measure the file itself; do not infer its dimensions from the request alone.

Logical display units and physical pixels can differ. Apple explains that a display scale maps logical points to backing pixels: a scale of 2 means two pixels per point in each dimension, and a scale of 3 means three. This is useful context for high-density device displays, but it does not specify the exact output dimensions of any CaptureKit device preset. See Apple’s UIScreen scale documentation.

Diagnose the mismatch in a controlled pass

Make a viewport-only request. Set explicit viewport dimensions and keep other options at their defaults where possible.
Check the parameter names in the request. The endpoint reference documents viewport_width and viewport_height. A CaptureKit playbook example uses width and height instead. The reviewed documentation does not establish whether these names are interchangeable. Inspect the actual query string and verify accepted names for the endpoint and version you call. See the CaptureKit screenshot playbook.
Read the returned image dimensions. Confirm the file’s actual pixel width and height with your image viewer or image-processing library.
Change only scale_factor. Capture again with the viewport, URL, and other settings unchanged, then compare the file dimensions.
Test full-page capture separately. If you enable full_page, expect page content beyond the viewport to affect the image height.
Test device emulation separately. Record the preset and compare with a request that does not select an emulated device, if the endpoint allows that configuration.

This is a diagnostic procedure based on the documented controls, not a guaranteed output formula. The endpoint documentation does not give one universal formula for final dimensions across device emulation, scale factor, and full-page combinations.

Build a minimal request, then add options

Start with the endpoint’s documented viewport parameter names. This cURL example shows the structure; use the authentication method and required fields specified for your CaptureKit account and endpoint.

curl -G 'https://YOUR-CAPTUREKIT-ENDPOINT' \\
  --data-urlencode 'url=https://example.com' \\
  --data-urlencode 'viewport_width=1280' \\
  --data-urlencode 'viewport_height=1024' \\
  --data-urlencode 'scale_factor=1'

Do not copy https://YOUR-CAPTUREKIT-ENDPOINT as a real URL. Replace it with the endpoint you use. Add authentication and any required output or format parameters from the official endpoint reference. Keep full_page disabled or omitted for the initial viewport-only diagnosis, then test it separately using the documented syntax.

Python request structure

import requests

endpoint = "https://YOUR-CAPTUREKIT-ENDPOINT"
params = {
    "url": "https://example.com",
    "viewport_width": 1280,
    "viewport_height": 1024,
    "scale_factor": 1,
}

response = requests.get(endpoint, params=params, timeout=90)
response.raise_for_status()
with open("capture.png", "wb") as image_file:
    image_file.write(response.content)

Replace the endpoint placeholder and add the authentication and output parameters required by your CaptureKit configuration. For repeatable comparisons, keep the destination URL and all unrelated request options fixed.

Node.js request structure

const endpoint = new URL("https://YOUR-CAPTUREKIT-ENDPOINT");
endpoint.search = new URLSearchParams({
  url: "https://example.com",
  viewport_width: "1280",
  viewport_height: "1024",
  scale_factor: "1",
}).toString();

const response = await fetch(endpoint);
if (!response.ok) {
  throw new Error(`Capture request failed: ${response.status} ${response.statusText}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import("node:fs/promises").then(({ writeFile }) => writeFile("capture.png", image));

As in the other examples, substitute your actual endpoint and configure authentication and output format according to CaptureKit’s endpoint documentation.

Parameter naming and configuration checks

Use the endpoint reference as the starting point. Its documented viewport names are viewport_width and viewport_height.
Inspect what your client sends. Framework wrappers, SDKs, and hand-built query strings can rename, omit, or overwrite values.
Do not silently mix examples. The playbook’s width/height example differs from the endpoint reference. Verify which names the endpoint/version accepts rather than assuming aliases.
Keep settings explicit during diagnosis. Set viewport dimensions and scale factor in the request so that defaults do not obscure what you intended.
Change one axis per capture. Compare viewport dimensions first, scale factor second, then full-page mode and device emulation as separate experiments.

Troubleshooting common dimension problems

Symptom	Likely cause	What to do
The output stays at the default-looking size.	The viewport fields may be missing, misspelled, or not accepted under the names sent.	Inspect the outgoing query string. Compare it with the endpoint reference’s `viewport_width` and `viewport_height` names and confirm the endpoint/version.
The width or height is larger than the viewport.	`full_page` may be capturing the page beyond the visible area, or a scale setting may affect output.	Run a viewport-only request, then vary scale and full-page mode independently. Measure the returned file.
The dimensions differ only when a device preset is selected.	Device emulation is an additional configuration axis and may use device-related dimensions or scaling.	Record the preset and compare it separately from a request without device emulation. Do not assume a preset’s pixel output from Apple’s general scale examples.
The screenshot has the expected viewport but looks soft or has unexpected pixel density.	The viewport and scale factor are different controls.	Check the file’s pixel dimensions and test an explicit `scale_factor` while holding viewport values constant.
A value in code looks correct, but the result is unchanged.	The client may serialize a different parameter name or override a value later in request construction.	Log or inspect the final URL/query parameters immediately before sending the request. Check for duplicate keys.
Full-page height varies between captures.	Page content height can depend on the page state and loaded content; the docs do not promise one fixed full-page output formula.	Keep the target and capture conditions stable, verify whether full-page is enabled, and compare the measured files.

Performance, reliability, and cost considerations

For dimension debugging, a small viewport-only request is easier to interpret than a full-page capture with device emulation and a high scale factor all enabled. Full-page capture can require more page content to be rendered, and high-resolution output can produce larger image files; treat those as practical considerations and measure them for your own pages rather than assuming a fixed cost or timing effect.

Make a few controlled captures and save the request parameters alongside each output. This creates a useful record if the issue recurs or the endpoint’s documented defaults change. The research sources provide documented parameter defaults, but no published benchmark, prevalence rate, or guarantee for output dimensions under every combination.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server. It accepts a URL in one GET request and returns an image or PDF. Its default capture workflow removes cookie and consent banners, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Only clean shots are billed: bot checks or CAPTCHAs, blank pages, timeouts, failed loads, and cache hits cost nothing, and responses identify the page verdict and billing status in headers.

Here is a direct call using the documented ScreenshotNeo API pattern. Replace the placeholder key with your API key. See the ScreenshotNeo API documentation.

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

import requests

r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);

ScreenshotNeo also provides an MCP server with take_screenshot, get_page_info, and capture_pdf tools for AI agents. The Free plan includes 1,000 shots each month with no card; paid plans start at $5 for 3,000 shots. Sign up for ScreenshotNeo’s free plan.

FAQ

Does a 1280 × 1024 viewport guarantee a 1280 × 1024 output image?

The endpoint documents those values as viewport defaults, but it does not document a universal output-dimension formula for every combination of full-page capture, device emulation, and scale factor. Measure the returned image.

Should I use `width` or `viewport_width`?

The endpoint reference uses viewport_width; a playbook example uses width. Verify the parameter accepted by the exact endpoint and version you call.

Does Apple’s Retina scale documentation tell me CaptureKit’s output size?

No. It explains the general relationship between logical points and backing pixels on Apple platforms. It does not define CaptureKit’s output for a specific device preset.

What should I include in a bug report?

Include the endpoint/version, final query parameter names and values, whether full-page capture is enabled, the device preset if any, the scale factor, and the measured output pixel dimensions. Redact credentials.