How to Capture a Website Screenshot at a Custom Viewport with ScreenshotAPI
Set a page’s viewport width and height to capture its responsive layout. See runnable ScreenshotAPI examples, capture modes, and troubleshooting tips.
To capture a website at a custom viewport with ScreenshotAPI, send the page URL with the desired width and height. Those dimensions control the visible browser area, so choose values that match the responsive layout or breakpoint you want to inspect. Leave full-page capture off for a viewport shot; enable it when you need the content below the fold too. ScreenshotAPI documents PNG, JPG, and WebP image output, as well as PDF. Check ScreenshotAPI’s current parameter reference for authentication and exact request syntax before using its API.
Choose the right capture area
A viewport screenshot shows what fits in the browser’s visible area at the requested width and height. A full-page screenshot captures the scrollable document. A selector or clip capture targets a particular element or rectangular region. These modes answer different questions, so pick the capture area before setting up the request.
| Goal | Capture mode | What to set |
|---|---|---|
| Check the visible responsive layout | Viewport | width and height; leave full-page off |
| Inspect content below the fold | Full page | width, height, and full_page=true |
| Capture just one component | Element or clip | A selector or clip rectangle, depending on the API option |
Set viewport dimensions for the page you are checking
- Choose the exact page URL, including its path and any query parameters needed to reproduce the page.
- Select the viewport width and height that correspond to the layout you want to inspect. For example, ScreenshotAPI lists 390×844 for mobile, 1024×768 for tablet, and 1440×900 for desktop. These are examples, not required presets or universal standards.
- Send the URL, dimensions, and any required authentication and output-format parameters using ScreenshotAPI’s current reference.
- Keep full-page capture off when you only want the initial visible area. Turn it on when the whole scrollable document is the deliverable.
- Open the returned image and check that it shows the intended responsive layout and enough content for your task.
Viewport dimensions describe the browser’s layout area. They do not by themselves guarantee a particular physical device, pixel density, or browser configuration. If a task requires a specific device environment, verify that the API offers the needed controls in its current documentation.
Use ScreenshotAPI
ScreenshotAPI’s custom viewport guidance uses a URL and chosen width and height; its getting-started material says to obtain an API key through its dashboard. The research available for this article does not establish the exact current authentication header or parameter name, nor a full copy-ready endpoint request. Use the live parameter reference to confirm authentication, endpoint, and output syntax rather than guessing. The shape of a request is:
GET SCREENSHOTAPI_ENDPOINT?url=ENCODED_PAGE_URL&width=VIEWPORT_WIDTH&height=VIEWPORT_HEIGHTSubstitute the endpoint and authentication method specified by ScreenshotAPI, URL-encode the page URL, and provide integer dimensions. Add the documented image format option if you need a particular image type. ScreenshotAPI describes PNG, JPG, and WebP output and also documents PDF; select a format supported by the current endpoint and plan for the consuming workflow.
Full-page capture
For a screenshot of the entire scrollable page, ScreenshotAPI documents full_page=true. Keep the same width so the page wraps at the responsive size you are testing. A full-page image can be much taller than a viewport image and may take longer to render or be harder to inspect in a diff.
GET SCREENSHOTAPI_ENDPOINT?url=ENCODED_PAGE_URL&width=390&height=844&full_page=trueElement or clip capture
If the goal is a component rather than the viewport, use the API’s documented selector or clip feature. ScreenshotAPI describes a clip region using x, y, width, and height. Confirm the current syntax and coordinate behavior in its reference; a clip is a distinct capture mode and does not replace choosing the page’s responsive viewport.
Pick an output format
- PNG: a lossless image format, useful when pixel detail matters.
- JPG: a compressed image format suitable when smaller files are preferred and transparency is unnecessary.
- WebP: an image format that may fit web delivery workflows; verify downstream support.
- PDF: choose this when the deliverable is document-style rather than a single image. ScreenshotAPI documents PDF output, but confirm its current PDF options separately.
Do not assume one format is always best. Follow the needs of the test, archive, or delivery system that consumes the capture.
Automate a set of viewport checks
For responsive checks, use a small, intentional dimension matrix based on the breakpoints your team supports. The example sizes below are values published by ScreenshotAPI, not a complete breakpoint policy.
| Example target | Width | Height | Useful for |
|---|---|---|---|
| Mobile example | 390 | 844 | Inspecting a compact layout |
| Tablet example | 1024 | 768 | Inspecting a medium-width layout |
| Desktop example | 1440 | 900 | Inspecting a wider layout |
Use the same URL, dimensions, capture mode, and output format across runs when comparing changes. Keep test data stable where possible: personalized content, rotating banners, current timestamps, and asynchronous page content can make screenshots differ even when the layout has not changed.
Performance, reliability, and cost considerations
- Render time: larger pages and full-page captures can involve more content than a simple viewport capture. Keep the requested area to what the task needs.
- Repeatability: use a stable page state and consistent dimensions. If the page depends on login, cookies, or query parameters, reproduce those conditions using options documented by the API.
- Dimensions: the reviewed ScreenshotAPI materials do not establish minimum or maximum dimensions, validation behavior, quotas, pricing, caching, or plan restrictions. Check the live parameter and account documentation before depending on those details.
- Output size: tall full-page images and lossless formats can produce larger files. Pick the format and capture area according to how the result will be stored or compared.
Troubleshooting
| Symptom | Likely cause | What to check |
|---|---|---|
| The screenshot has the wrong responsive layout | The requested width does not match the intended breakpoint, or the dimensions were not sent as expected. | Inspect the actual request, confirm width and height in the current API reference, and try the exact target width. |
| The image shows only the top of the page | The request captured the viewport rather than the full document. | Use the documented full_page=true option when you need the scrollable page. |
| The requested page URL is not captured correctly | The URL may not be encoded correctly, or required query parameters may be missing. | URL-encode the target URL and preserve the path and query string. Confirm authentication and request syntax in ScreenshotAPI’s reference. |
| The result is an unexpected format | The output parameter may be absent, unsupported, or named differently in the current endpoint. | Check the current format parameter and request PNG, JPG, WebP, or PDF as supported. |
| A component is missing or clipped | A viewport capture includes only the visible region, or a selector/clip targets a different area. | Decide whether you need full-page, selector, or clip capture and verify the current selector or coordinate syntax. |
| The API rejects dimensions | The values may be malformed or outside undocumented constraints. | Send integer width and height values and consult the current detailed parameter reference for limits and validation rules. |
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server for developers. One GET request takes a URL and returns PNG, JPEG, WebP, or PDF. Set the viewport with width and height; see the ScreenshotNeo API documentation for the available options and authentication details.
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://stripe.com -o shot.webpimport requests
r = requests.get(
"https://api.screenshotneo.com/v1/shot",
params={
"access_key": "YOUR_API_KEY",
"url": "https://stripe.com",
"width": 390,
"height": 844,
},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({
access_key: 'YOUR_API_KEY',
url: 'https://stripe.com',
width: '390',
height: '844',
});
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`ScreenshotNeo returned ${res.status}`);
await Bun.write('shot.webp', res);ScreenshotNeo removes cookie banners, newsletter popups, and chat widgets before the shot; each cleanup step can be turned off. Bot checks, blank pages, and failed loads are never billed. 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. Learn about ScreenshotNeo, then sign up for 1,000 free screenshots a month with no card.
FAQ
Do width and height mean the screenshot’s output pixel dimensions?
They are the requested browser viewport dimensions in ScreenshotAPI’s custom viewport guidance. Check the API’s current reference for any separate scale or output-size controls.
Should I use full-page mode for responsive testing?
Only if the content below the fold matters to the check. For the visible browser area at a breakpoint, use a viewport capture.
Which dimensions should I use?
Use dimensions that match the layout or breakpoint under test. The published mobile, tablet, and desktop examples are starting points, not universal requirements.
Can I capture a single element instead?
Yes. ScreenshotAPI documents selector and clip alternatives; consult its current reference for exact request syntax.
