How to Set the Viewport Size in CaptureKit Screenshot Requests
Set CaptureKit’s viewport with viewport_width and viewport_height in pixels. Here are runnable examples, full-page distinctions, and fixes for common request issues.
Set viewport_width and viewport_height on CaptureKit’s GET /v1/capture request. Both values are pixel dimensions for the browser viewport. The documented defaults are 1280 pixels wide by 1024 pixels high. Send your API key in the x-api-key header.
For example, to capture a 1440 × 900 viewport, request viewport_width=1440 and viewport_height=900. These dimensions determine the browser area used to render the page; they do not, by themselves, make the screenshot full-page. CaptureKit’s capture endpoint reference documents the endpoint parameters and defaults.
1. Make a request with a custom viewport
Choose dimensions that represent the browser viewport you need to reproduce, such as a desktop or mobile layout. Include the target URL, both viewport dimensions, and your API key. Keep the key in a server-side environment variable; do not put it in public source code or client-side browser requests.
cURL
export CAPTUREKIT_API_KEY="YOUR_API_KEY"
curl -G "https://api.capturekit.dev/v1/capture" \
-H "x-api-key: $CAPTUREKIT_API_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "viewport_width=1440" \
--data-urlencode "viewport_height=900" \
--data-urlencode "format=png" \
-o screenshot.pngThe response is an image for a successful image capture. Choose a matching file extension for the format you request.
Python
This example uses the third-party requests package. Install it with python -m pip install requests if it is not already available.
import os
import requests
api_key = os.environ["CAPTUREKIT_API_KEY"]
response = requests.get(
"https://api.capturekit.dev/v1/capture",
headers={"x-api-key": api_key},
params={
"url": "https://example.com",
"viewport_width": 1440,
"viewport_height": 900,
"format": "png",
},
timeout=90,
)
response.raise_for_status()
with open("screenshot.png", "wb") as image_file:
image_file.write(response.content)Node.js
With a Node.js version that provides the built-in fetch, the request can be written without an additional HTTP package:
const apiKey = process.env.CAPTUREKIT_API_KEY;
if (!apiKey) throw new Error("Set CAPTUREKIT_API_KEY first");
const params = new URLSearchParams({
url: "https://example.com",
viewport_width: "1440",
viewport_height: "900",
format: "png",
});
const response = await fetch(
`https://api.capturekit.dev/v1/capture?${params}`,
{ headers: { "x-api-key": apiKey } },
);
if (!response.ok) {
const message = await response.text();
throw new Error(`CaptureKit returned ${response.status}: ${message}`);
}
const image = Buffer.from(await response.arrayBuffer());
const { writeFile } = await import("node:fs/promises");
await writeFile("screenshot.png", image);Use URLSearchParams or your HTTP client’s query-parameter facility so the target URL and other values are encoded correctly.
2. Choose viewport dimensions for the capture
The dimensions are browser viewport width and height in pixels. Set both explicitly when you need repeatable output across requests. If you omit them, the endpoint reference lists defaults of 1280 × 1024.
| Goal | What to set | What it controls |
|---|---|---|
| Match a desktop layout | viewport_width and viewport_height to the desired desktop dimensions |
The browser’s visible layout area |
| Match a narrow responsive layout | Use a smaller width and the height needed for the visible capture | Responsive breakpoints and visible area |
| Capture more vertical content | Set the viewport, then separately enable full_page=true |
Full-page capture coverage |
| Use CaptureKit’s documented defaults | Omit both dimensions | 1280 px wide × 1024 px high |
A viewport is not a physical device by itself. If you need device emulation, the endpoint also documents a device parameter with supported presets. For a known pixel size, use the viewport parameters; for a preset device profile, consult the endpoint’s current device list and verify the resulting layout in your own integration.
Viewport capture versus full-page capture
viewport_width and viewport_height set the browser dimensions. full_page controls whether the screenshot covers the entire page rather than only the visible viewport. It is a separate option and defaults to false in the endpoint reference.
curl -G "https://api.capturekit.dev/v1/capture" \
-H "x-api-key: $CAPTUREKIT_API_KEY" \
--data-urlencode "url=https://example.com" \
--data-urlencode "viewport_width=1440" \
--data-urlencode "viewport_height=900" \
--data-urlencode "full_page=true" \
--data-urlencode "full_page_scroll=true" \
--data-urlencode "format=png" \
-o full-page.pngThe endpoint separately documents full_page_scroll and full_page_scroll_duration for scrolling to load lazy content before a full-page capture. Use these when below-the-fold elements appear only after scrolling. The viewport dimensions still describe the browser viewport; they are not a substitute for the full-page setting.
3. Use format and other relevant capture options
Viewport dimensions work alongside the endpoint’s other query parameters. The options below are relevant when determining how the captured result should be rendered or returned; check the live reference for the complete current parameter list.
| Parameter | Purpose | Notes |
|---|---|---|
url |
Required page URL to capture | Encode it as a query parameter, especially when it contains its own query string. |
viewport_width, viewport_height |
Browser viewport dimensions in pixels | Reference defaults are 1280 and 1024 respectively. |
format |
Output type | Documented values include png, jpeg, jpg, webp, and pdf; default is PNG. |
full_page |
Capture beyond the visible area | Separate from the viewport size; default is false. |
full_page_scroll |
Scroll before a full-page capture to load lazy elements | Use for pages whose content loads as the page is scrolled. |
full_page_scroll_duration |
Scrolling duration in milliseconds | Relevant to full-page scrolling behavior. |
device |
Emulate a documented device preset | See the endpoint reference for supported preset names. |
CaptureKit’s endpoint reference lists the capture call at one credit per call. Use its current endpoint documentation for available options and its current API introduction for authentication and response behavior.
4. Resolve the parameter-name discrepancy
CaptureKit’s endpoint reference documents viewport_width and viewport_height. Its official playbook examples have also used width and height. Those sources conflict, so do not assume the short names are interchangeable with the reference names for every endpoint version.
Start with the endpoint reference names shown in this guide. If the returned image still uses an unexpected viewport, inspect the actual outgoing query string and compare it with the current endpoint reference. CaptureKit’s playbook example is useful context for the discrepancy, but the endpoint parameter listing is the more direct reference for /v1/capture.
5. Keep credentials and requests reliable
- Send authentication in the header. Include
x-api-keyon each request, and load its value from a secret store or server-side environment variable. - Do not expose the key in browser code. A user can inspect client-side requests and recover a key embedded in the page. Proxy capture requests through your backend.
- Encode query values. Use a URL builder or HTTP library’s parameter encoder instead of concatenating an unescaped target URL into the request.
- Check HTTP status before saving the body. On failure, the body may describe an error rather than contain an image. Log the status and safe diagnostic message, not the API key.
- Set a reasonable client timeout. Page rendering can take longer than a small API call. Choose a timeout appropriate to your workflow and handle timeouts without treating an error body as an image.
- Retry selectively. For transient network or server errors, use bounded retries with backoff. Do not retry authentication, invalid-parameter, or other deterministic errors unchanged.
CaptureKit’s documentation says successful synchronous calls are billed; its introduction describes API error status behavior and recommends keeping credentials private. Check the current billing documentation before estimating production volume.
6. Troubleshoot common problems
| Symptom | Likely cause | Fix |
|---|---|---|
| The screenshot has the wrong width or height | A dimension parameter is missing, misspelled, or sent under the playbook’s alternate width/height names. |
Inspect the outgoing query. Set both viewport_width and viewport_height as listed in the endpoint reference. Check the current endpoint docs if the behavior persists. |
| The screenshot stops at the viewport | full_page was omitted or false. |
Set full_page=true. Viewport height does not request a full-page image. |
| Images or sections are missing lower down | Content is lazy-loaded and the page was not scrolled before capture. | For full-page captures, enable full_page_scroll=true; consult the endpoint reference for its scroll-duration option. |
| HTTP 401 | The x-api-key header is absent, incorrect, inactive, or expired; rate limiting can also produce 401. |
Verify the header and key in the account dashboard. Read the response message to distinguish authentication from a rate limit. |
| HTTP 400 | A required URL or parameter is invalid, or a value has the wrong type or encoding. | Check the endpoint parameter names and encode the target URL through a query builder. |
| HTTP 402 | The account needs credits or billing attention. | Check the account balance and billing settings. |
| HTTP 500 or client timeout | The capture failed on the service or took longer than the client allows. | Check the status and error body, increase the client timeout when appropriate, and retry transient failures with a bounded backoff policy. |
| A saved “PNG” file is invalid | The client wrote a JSON/text error response to an image filename. | Check response.ok or call raise_for_status() before saving bytes; inspect the error response separately. |
For current response codes and handling guidance, see CaptureKit’s error-handling documentation.
7. Performance, reliability, and cost
Larger viewport dimensions can cause more page content to be visible and may increase the amount of page work and output data. Full-page capture can include substantially more content than a viewport-only capture; scrolling to trigger lazy content adds work as well. Choose the smallest dimensions that answer your use case, and enable full-page scrolling only when needed.
For predictable captures, explicitly pass both viewport dimensions, the format, and any full-page options. Keep a request timeout, check status codes, and make retries bounded. CaptureKit lists one credit per capture call; its pricing and plan details can change, so review the current pricing page before calculating recurring costs. A failed request’s billing treatment is status- and endpoint-specific; use the current documentation rather than assuming all failures have the same cost.
8. 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 API accepts the parameter names used by other screenshot APIs, making it straightforward to try with a custom viewport. See the ScreenshotNeo API documentation for its request options.
curl -G "https://api.screenshotneo.com/v1/shot" \
-d access_key=YOUR_API_KEY \
--data-urlencode url=https://example.com \
-d viewport_width=1440 \
-d viewport_height=900 \
-o shot.webpWith ScreenshotNeo, cookie banners are accepted and removed before the shot, along with known consent platforms, newsletter popups, and chat widgets; each of these steps can be turned off. Bot checks, blank pages, and failed loads are never billed, and response headers identify the page verdict and whether the request was billed. Its MCP server lets AI agents take screenshots. The free plan includes 1,000 screenshots a month with no card; paid plans start at $5 for 3,000 screenshots.
Sign up free for ScreenshotNeo: 1,000 screenshots a month, no card required.
9. Frequently asked questions
Are viewport dimensions measured in CSS pixels or image pixels?
CaptureKit describes them as browser viewport dimensions in pixels. The endpoint reference does not specify a separate device-pixel-ratio interpretation, so do not assume these values also determine output pixel density.
What happens if I set only the width?
The documented defaults are 1280 for width and 1024 for height. For reproducible captures, send both values rather than relying on one default.
Does changing viewport height make the result full-page?
No. Height sets the viewport dimension. Use full_page=true when you want the entire page.
Can I use a device preset and custom dimensions together?
The endpoint reference lists both device presets and viewport parameters, but the provided documentation does not establish precedence when they are combined. Verify the behavior against the current endpoint documentation for your specific request.
