HTMLCSStoImage Screenshot Dimensions Are Wrong: How to Fix Viewport Settings

If an HTMLCSStoImage screenshot has the wrong dimensions, first set viewport_width and viewport_height together to control the browser’s layout area. Then check device_scale for the output pixel density, and full_screen, selector, or content sizing for the captured area. These settings affect different things.

The viewport is measured in CSS pixels. It determines the space available to the page and which responsive breakpoints apply. It does not necessarily equal the final image’s pixel dimensions: HTML/CSS to Image documents 2x rendering by default, while device_scale: 1 requests 1x output. See the vendor’s viewport documentation and parameter reference.

1. Set the viewport width and height together

Use both viewport parameters when you need a specific browser layout area. The documented default is 1920×1080 CSS pixels, and the maximum viewport width is 6000 CSS pixels. Explicit viewport dimensions disable automatic cropping and return the area rendered inside the viewport.

{
  "url": "https://example.com",
  "viewport_width": 1200,
  "viewport_height": 630
}

This asks the browser to lay out the page in a 1200×630 CSS-pixel viewport. If the page is responsive, its CSS media queries will respond to that width. A 1200 CSS-pixel layout does not promise a 1200-pixel-wide file if the output scale is greater than 1.

2. Check viewport size versus output resolution

Diagnose the mismatch by identifying what is wrong:

The layout or breakpoint is wrong: adjust viewport_width and viewport_height.
The layout looks right, but the image has more pixels than expected: set device_scale, commonly to 1 for 1x output.
The visible region or image shape is wrong: check full-page capture, element cropping, or content sizing.

For example, retain a 1200×630 CSS viewport but request 1x output:

{
  "url": "https://example.com",
  "viewport_width": 1200,
  "viewport_height": 630,
  "device_scale": 1
}

The parameter reference gives device_scale a supported range of 0.1 to 3. The FAQ says rendering is 2x by default. Choose the scale for the required output density; changing it does not change the CSS layout viewport.

3. Configure a mobile viewport when needed

Use mobile-sized dimensions for the layout you want to inspect. Set viewport_mobile: true when you also need mobile viewport behavior, including the page’s <meta name="viewport"> settings. The width and height still determine the dimensions; the mobile flag does not select them for you.

{
  "url": "https://example.com",
  "viewport_width": 390,
  "viewport_height": 844,
  "viewport_mobile": true,
  "device_scale": 1
}

Use a desktop viewport without the mobile flag when checking desktop breakpoints. If the page still appears to use the wrong layout, verify its responsive CSS and viewport meta tag as well as the request parameters.

4. Check whether you are capturing a viewport, full page, or element

Ordinary viewport capture returns the rendered viewport area. With full_screen: true, HTML/CSS to Image captures the full scrollable page, so the image can be taller than viewport_height. Remove that option when you want only the initial viewport.

{
  "url": "https://example.com",
  "viewport_width": 1200,
  "viewport_height": 630,
  "full_screen": true
}

Keep full_screen only when the full page is the intended result. To capture one component, use the documented selector parameter for that element. For a small standalone HTML graphic where tight automatic trimming is desired, the vendor guidance is to size the content in CSS rather than set explicit viewport dimensions.

5. Do not use output resizing to fix responsive layout

The API’s width and height query parameters resize the generated image without changing the viewport or rerendering the page. They are appropriate when the rendered image is correct and only its final file dimensions need resizing. They do not make the browser render at a different responsive breakpoint.

For a layout correction, change the viewport and capture again. For a file-size correction, use the documented resizing parameters or select the appropriate device_scale, depending on whether you want a resized result or a different render resolution.

6. Runnable API examples

These examples request a 1200×630 CSS viewport at 1x output. Replace the example URL with the page you need to capture. Check the viewport parameter docs and full parameter reference for the current endpoint and authentication requirements for your account.

cURL

curl -G "https://hcti.io/v1/image" \
  -H "Authorization: Basic YOUR_AUTH_HEADER" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "viewport_width=1200" \
  --data-urlencode "viewport_height=630" \
  --data-urlencode "device_scale=1" \
  -o screenshot.png

Use the endpoint and authentication format from your HTML/CSS to Image account if they differ from this request format. Keep credentials out of public client-side code.

Python

import requests

response = requests.get(
    "https://hcti.io/v1/image",
    auth=("YOUR_USER_ID", "YOUR_API_KEY"),
    params={
        "url": "https://example.com",
        "viewport_width": 1200,
        "viewport_height": 630,
        "device_scale": 1,
    },
    timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
    image_file.write(response.content)

Node.js

const params = new URLSearchParams({
  url: 'https://example.com',
  viewport_width: '1200',
  viewport_height: '630',
  device_scale: '1',
});

const credentials = Buffer.from('YOUR_USER_ID:YOUR_API_KEY').toString('base64');
const response = await fetch(`https://hcti.io/v1/image?${params}`, {
  headers: { Authorization: `Basic ${credentials}` },
  signal: AbortSignal.timeout(90000),
});

if (!response.ok) {
  throw new Error(`Screenshot request failed: ${response.status} ${await response.text()}`);
}

const fs = await import('node:fs/promises');
await fs.writeFile('screenshot.png', Buffer.from(await response.arrayBuffer()));

These examples show the viewport-related parameters and a common request shape. Use the vendor’s current API documentation for account-specific authentication or endpoint differences.

7. Troubleshoot common dimension problems

Symptom	Likely cause	Fix
Only one dimension seems to take effect	Only one of `viewport_width` and `viewport_height` was supplied.	Send both viewport dimensions together.
The layout is correct, but the file is twice the expected pixel dimensions	The default 2x output scale.	Set `device_scale: 1` for 1x output, keeping the viewport values unchanged.
The mobile page shows its desktop layout	The request uses a desktop viewport behavior, or its dimensions do not match the desired mobile breakpoint.	Set mobile-sized width and height and use `viewport_mobile: true` when mobile viewport behavior is needed.
The image is unexpectedly tall	`full_screen: true` captures the whole scrollable page.	Remove it for a viewport capture, or keep it when the full page is the intended result.
A component has too much surrounding content	The request captures the viewport or page rather than a specific element.	Use `selector` to target the element.
A small HTML graphic has excess margins	Explicit viewport dimensions can disable automatic cropping.	Size the snippet in CSS and follow the vendor guidance for automatic trimming instead of setting explicit viewport dimensions.
The image file is smaller or larger after resizing, but the layout has not changed	`width` and `height` resize the result without rerendering.	Use viewport dimensions to change layout; use output resizing only to change the resulting file dimensions.
Dimensions look right, but text or images are missing	Dynamic content may not be ready when capture starts.	Use `ms_delay` for a fixed wait, or `render_when_ready` for pages that call `ScreenshotReady()`. These affect readiness, not viewport geometry.
The requested viewport width is rejected or unavailable	The documented maximum viewport width is 6000 CSS pixels.	Keep the width within that limit and use output resizing if the final file needs a different size.

8. Performance, reliability, and cost considerations

Larger viewport dimensions and higher device scale produce more image pixels to render and transfer. Use the smallest viewport that includes the layout you need, and avoid full-page capture when a viewport or element capture is enough. These choices control workload and output size; the dossier provides no measured timing or cost figures for particular dimensions.

For reliable captures of JavaScript-rendered pages, distinguish readiness from geometry. A delay or the page’s ScreenshotReady() signal can help ensure content has appeared, but neither corrects the viewport. Keep viewport values explicit in production requests when repeatable responsive output matters, and treat dynamic page content as a separate source of variation.

9. Or skip the browser setup

ScreenshotNeo provides a screenshot API and MCP server. Its GET API accepts a URL and returns a PNG, JPEG, WebP, or PDF. Here is the one-call form for a capture:

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

See the ScreenshotNeo API documentation for viewport and other request options. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed; and its MCP server lets AI agents take screenshots. The Free plan includes 1,000 screenshots a month with no card, and paid plans start at $5 for 3,000.

10. FAQ

What is the default HTMLCSStoImage viewport?

The vendor documentation lists 1920×1080 CSS pixels as the default viewport.

What is the maximum viewport width?

The documented maximum is 6000 CSS pixels wide.

Does `viewport_mobile` set a mobile width automatically?

No. Specify the width and height you want, then enable the flag if you need mobile viewport behavior.

Set the viewport to make the page render at the intended layout breakpoint and area. Resize the output only if you need to alter the resulting file without changing that layout.