Resolution

Two ways to change the size, and they are not the same one

Rendering at 2× and shrinking to 400 px are opposite operations, and confusing them is how a thumbnail pipeline ends up too expensive or too soft.

device_scale_factorimage_widthimage_heightimage_qualityviewport_width

curl --fail-with-body "https://api.pagecapture.dev/v1/take" \
  -H "X-Access-Key: $PAGECAPTURE_KEY" \
  -H "Content-Type: application/json" \
  --data '{"url":"https://example.com","format":"jpg","device_scale_factor":2,"image_width":1200,"image_quality":82}' \
  -o capture.jpg

Verified 2026-08-13 by running the published code against a fixture.

Configure it in the playground

What it does

Renders at up to 5× device pixel ratio, which is what makes a capture sharp on a retina display rather than upscaled.
Resizes the encoded output with `image_width` and `image_height`, preserving aspect ratio when only one is given.
Keeps `image_quality` as the separate lossy-encoder dial, defaulting to 80.

What it does not do

Does not make resizing and scaling interchangeable. Resizing throws detail away after the render; scale adds it during.
Does not resize on `/v1/animate`. `image_width` and `image_height` apply to `/v1/take`; a recording sets its size with `width`, `height` and `aspect_ratio`.
Does not protect you from the pixel budget. A large viewport at a high scale is what `resulting_image_too_large` is reporting.

The contract

Every limit on this page is the one the API enforces

These rows are read from the same parameter table that validates your request. Nothing here is transcribed, so a number cannot drift from the behaviour it describes.

Parameter	Type	Default	Range	Endpoints	Cache key
`device_scale_factor` Pixel density multiplier (2 = retina).	number	1	1 – 5	/v1/take, /v1/animate	In
`image_width` Resize output width. Aspect ratio is preserved when height is omitted.	integer	—	1 – 20,000	/v1/take	In
`image_height` Resize output height.	integer	—	1 – 20,000	/v1/take	In
`image_quality` Encoder quality for lossy formats.	integer	80	1 – 100	/v1/take, /v1/animate	In
`viewport_width` Viewport width in CSS pixels.	integer	1280	50 – 7,680	/v1/take, /v1/animate	In

Group: Viewport and deviceValues outside a documented range are rejected before a browser opens.

How it behaves next to the rest of the request

viewport_width

Viewport width in CSS pixels.

The viewport decides layout; scale decides density. A 1280 px viewport at 2× is a desktop layout rendered at 2560 real pixels — not a 2560 px desktop layout.

image_width

Resize output width. Aspect ratio is preserved when height is omitted.

The cheap way to a thumbnail: render once at a sensible scale and resize down. Rendering small to save bytes gives you a mobile layout instead.

viewport_device

Device preset id. Sets width, height, scale, touch, mobile and user agent together.

A device preset sets width, height, scale, touch and user agent together, which is what you want when the goal is 'what an iPhone sees' rather than a specific pixel count.

Errors this option can produce

resulting_image_too_largeHTTP 400

The resulting image exceeds the maximum allowed size.

None of them is billable. No error code in the catalog is.

Questions this raises

Which one should I use for thumbnails?

Both, in this order: render at 2× so the source is sharp, then set `image_width` to the size you actually publish. Rendering small is not a thumbnail, it is a mobile capture.

Why did raising the scale break my full-page capture?

Scale multiplies both axes, so 2× is four times the surface. On a tall document that is what pushes the render past the pixel budget — cap it with `full_page_max_height` or lower the scale.

Does resizing cost extra?

No. It happens in the same successful capture, and the price is one credit either way.