How to set the viewport size in an HTMLCSStoImage request

Set both viewport_width and viewport_height on the create-image request. For example, use 1200 by 630 for a 1200 × 630 CSS-pixel viewport. These values control the virtual browser area and responsive layout; they do not necessarily determine the final image’s pixel dimensions.

1. Set both viewport dimensions

The HTML/CSS to Image create-image endpoint is POST https://hcti.io/v1/image. Send either a url or html value, not both. The css field is optional. Add both viewport fields to the same request. See the viewport parameter documentation and the API usage guide.

curl -X POST https://hcti.io/v1/image \
  -u 'YOUR_USER_ID:YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "viewport_width": 1200,
    "viewport_height": 630
  }'

Replace the credentials with your HTML/CSS to Image account values. The request returns the generated image information. Use the returned image URL or your client’s documented response handling to retrieve the image.

Python

import requests

response = requests.post(
    "https://hcti.io/v1/image",
    auth=("YOUR_USER_ID", "YOUR_API_KEY"),
    json={
        "url": "https://example.com",
        "viewport_width": 1200,
        "viewport_height": 630,
    },
    timeout=90,
)
response.raise_for_status()
print(response.json())

Node.js

const credentials = Buffer.from("YOUR_USER_ID:YOUR_API_KEY").toString("base64");

const response = await fetch("https://hcti.io/v1/image", {
  method: "POST",
  headers: {
    Authorization: `Basic ${credentials}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example.com",
    viewport_width: 1200,
    viewport_height: 630,
  }),
});

if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
console.log(await response.json());

2. Choose dimensions for the layout you need

Viewport values are integer CSS pixels. The width determines which responsive breakpoints and media queries apply; height sets the visible viewport height. Choose the pair to match the browser layout you want to reproduce, rather than assuming it matches a target image’s output pixels.

Use case	Viewport pair	Notes
Desktop social preview	1200 × 630	Use when the page should lay out at a wide desktop breakpoint.
Mobile page	390 × 844	Also set viewport_mobile: true when mobile viewport behavior is required.
Default rendering	1920 × 1080	The viewport documentation gives this as the default when dimensions are omitted.

The documented maximum viewport width is 6000. The documentation requires both width and height when setting the viewport; do not send only one.

3. Configure mobile, landscape, and touch behavior

A small viewport pair alone does not enable mobile emulation. Add viewport_mobile: true to enable Chrome mobile viewport behavior, including support for the page’s <meta name="viewport"> settings. Optional viewport_landscape and viewport_touch booleans default to false. These change device behavior; they do not set the dimensions.

curl -X POST https://hcti.io/v1/image \
  -u 'YOUR_USER_ID:YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "url": "https://example.com",
    "viewport_width": 390,
    "viewport_height": 844,
    "viewport_mobile": true,
    "viewport_landscape": false,
    "viewport_touch": true
  }'

4. Keep viewport, output resolution, and capture bounds separate

Changing viewport dimensions affects the page’s CSS layout. Other settings control different parts of the result:

Setting	What it changes
viewport_width and viewport_height	Virtual browser viewport in CSS pixels and the resulting responsive layout.
device_scale	Output pixel resolution while leaving the CSS viewport unchanged. The documented range is 0.1 to 3; the FAQ says output is 2× by default and recommends 1 for 1×.
full_screen	Captures page content below the initial viewport for URL screenshots.
selector	Crops the capture to an element within the configured viewport.
Generated image URL width and height query parameters	Resize the generated image without changing the viewport or rerendering the page.

For example, to keep a 1200 × 630 CSS layout and request 1× output, include "device_scale": 1 alongside both viewport fields. If you instead need the entire long page, use the full-screen option; increasing viewport height is not the same capture instruction.

5. Troubleshooting common viewport issues

Symptom	Likely cause	Fix
The request fails after setting one dimension.	The API requires width and height as a pair.	Send both viewport_width and viewport_height as integers.
The page still uses desktop styling at a narrow width.	A narrow viewport does not by itself enable mobile viewport emulation, or the page’s breakpoint differs from the chosen width.	Set viewport_mobile: true if mobile behavior is needed, and choose a width that crosses the site’s responsive breakpoint.
The image has more pixels than expected.	Output resolution is separate from CSS viewport size; the FAQ describes 2× output by default.	Set device_scale: 1 for documented 1× output, or resize using the generated image URL’s width and height parameters.
The bottom of the page is missing.	The capture is limited to the viewport.	For a URL screenshot, enable full_screen to capture below the initial viewport.
The result contains only one component.	A selector crop is active.	Remove selector for the viewport capture, or use it intentionally to capture a specific element.
A request is rejected for an excessive width.	The width exceeds the documented maximum.	Keep viewport_width at or below 6000 and choose a supported layout size.

6. Performance, reliability, and cost considerations

Use the smallest viewport that represents the layout you need, and avoid rerendering when a generated image URL can resize the existing output. Use device_scale to choose output resolution independently from responsive layout. For reliable results, keep the viewport pair explicit in production requests so a change in defaults cannot alter the intended breakpoint. Handle HTTP errors and request timeouts in your client, and inspect the returned response before treating a capture as successful.

The research documentation establishes viewport settings and output behavior, but does not specify per-request pricing, timing guarantees, or a cost model. Check your account’s current plan and API documentation for those details.

7. Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. A single GET request can return a PNG, JPEG, WebP, or PDF. To choose a viewport, pass its width and height parameters; see the ScreenshotNeo API documentation.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://example.com \
  -d width=1200 \
  -d height=630 \
  -o shot.webp

import requests

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

const q = new URLSearchParams({
  access_key: "YOUR_API_KEY",
  url: "https://example.com",
  width: "1200",
  height: "630",
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`HTTP ${res.status}`);
await Bun.write("shot.webp", res);

• Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
• Bot checks, blank pages, failed loads, timeouts, and cache hits are not billed; response headers identify the page verdict and billing status.
• An MCP server lets AI agents use take_screenshot, get_page_info, and capture_pdf.
• The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000.

Start with 1,000 free screenshots a month, no card required.

8. Frequently asked questions

Can viewport dimensions be decimals?

The documented values are integer CSS-pixel dimensions. Send whole numbers for width and height.

Does viewport width set the image’s final pixel width?

No. It sets the virtual browser layout width. Output scale and post-render resizing control the image pixels separately.

Do I need mobile emulation for a tablet-sized layout?

Use dimensions that match the tablet breakpoint. Enable viewport_mobile when the page needs mobile viewport behavior, such as honoring its viewport meta tag.

Can I use viewport parameters with HTML input instead of a URL?

Yes. The create-image API accepts either url or html; viewport fields are additional request parameters. Do not provide both input fields in the same request.