How to Set the Viewport Size in a Thumbalizr Screenshot
Set Thumbalizr’s browser viewport with bwidth and bheight. Learn the plan limits, how viewport size differs from output width, and how to check a capture.
Set the browser viewport in a Thumbalizr Embed API request with bwidth and bheight, measured in pixels. The width parameter controls the thumbnail’s output width; it does not set the browser viewport. On Free and Silver, the documented browser size is fixed at 1280 × 1024. Gold and Platinum allow custom dimensions, subject to their tier limits.
1. Add the viewport parameters
Start with the page URL, then add bwidth and bheight to set the browser dimensions used to render the page. For example, a 1440 × 900 viewport uses bwidth=1440&bheight=900, provided your plan allows those values.
https://www.thumbalizr.com/api/?url=https%3A%2F%2Fexample.com&bwidth=1440&bheight=900This illustrates the relevant parameters; use the request format and authentication or signing requirements for your Thumbalizr account. The API documentation says url is the only required parameter and other parameters may use defaults from the account profile. See the Thumbalizr API documentation for the current request details.
Encode the target URL
URL-encode the target page when building the request. This matters especially when the target itself contains query parameters, fragments, or reserved characters. Prefer a URL builder or an HTTP client’s parameter encoding over manually concatenating strings.
2. Check your plan’s dimension limits
| Plan | Browser viewport width | Browser viewport height | Capture extent |
|---|---|---|---|
| Free | Fixed at 1280 px | Fixed at 1024 px | Screen capture |
| Silver | Fixed at 1280 px | Fixed at 1024 px | Screen or full page |
| Gold | 1–1600 px | 1–1600 px | Screen or full page |
| Platinum | 1–2000 px | 1–2000 px | Screen or full page |
The current API parameter table gives Gold’s maximum as 1600 pixels per dimension. Some Thumbalizr feature summaries describe paid dimensions more generally; use the API documentation and your account’s current plan details when choosing exact values. Plan features can change.
3. Keep viewport size, output width, and capture extent separate
| Parameter | What it controls | Example use |
|---|---|---|
bwidth |
Browser viewport width in pixels | Render at a desktop viewport width of 1440 |
bheight |
Browser viewport height in pixels | Render at a viewport height of 900 |
width |
Thumbnail image output width | Scale the resulting thumbnail to a chosen width |
size |
Capture extent: visible screen or full page | size=screen or, when supported, size=page |
For example, bwidth=1440&bheight=900&width=600 requests a page rendered in a 1440 × 900 browser viewport and a thumbnail output width of 600 pixels. The output width does not change the viewport at which the page is laid out.
4. Choose screen or full-page capture
Use size=screen to capture the visible browser screen. Use size=page for a full-page capture when the account tier supports it. Free is documented as screen-only; Silver, Gold, and Platinum include screen or full-page capture according to Thumbalizr’s current feature descriptions.
Full-page extent and viewport dimensions answer different questions: bwidth and bheight set the browser viewport, while size determines whether the capture covers the screen or page. Check your plan before relying on full-page output.
5. Confirm the request result
For API responses, inspect the X-Thumbalizr-Status header. Documented values include QUEUED, OK, and FAILED. The API may also return generation-time and error headers. A queued response means processing is not yet confirmed as complete; follow the API’s documented response flow and check for a final status.
Common problems and fixes
| Symptom | Likely cause | What to do |
|---|---|---|
| The capture stays at 1280 × 1024 | Free and Silver use fixed browser dimensions. | Use a tier that supports custom dimensions, then set both bwidth and bheight. |
| The page layout does not match the requested width | width was changed instead of bwidth, or the plan does not permit the requested viewport. |
Set bwidth and bheight within your tier’s limits. Set width only for output image width. |
| The request fails for a larger viewport | The requested value may exceed the account tier’s documented maximum. | Reduce either dimension to the allowed range or confirm current limits in the API documentation. |
| The result shows only the first screen | The request uses screen capture, or the tier does not include full-page capture. | Set size=page if your tier supports it. |
| The target URL is malformed | Nested query parameters or reserved characters were not encoded. | Encode the target URL as a parameter using a URL or HTTP library. |
The status is QUEUED or FAILED |
The capture has not completed, or Thumbalizr reported a failure. | Use the documented API response flow; inspect available error headers and confirm the final status is OK. |
Performance, reliability, and cost considerations
- Request the dimensions you need. The viewport determines page layout and capture dimensions, while output width controls thumbnail sizing. Avoid confusing the two when diagnosing an unexpected image.
- Allow for asynchronous processing. A
QUEUEDstatus is not a completed capture. Check the final response status using the documented API flow. - Choose the plan based on capability. The key tier differences for this task are custom viewport dimensions and screen versus full-page capture. Check Thumbalizr’s live features and pricing page for current plan details and quotas.
- Protect signing secrets. Thumbalizr documents URL signing with an MD5 token derived from the query string and account secret, and warns against exposing the API key in public pages. Keep secrets on a server you control and consult the current documentation for the recommended Embed API usage.
Or skip the browser setup
ScreenshotNeo provides a screenshot API: one GET request takes a URL and returns PNG, JPEG, WebP, or PDF. Its API supports custom viewport sizes and other capture options; see the ScreenshotNeo API documentation for request parameters.
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"},
timeout=90,
)
open("shot.webp", "wb").write(r.content)const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);- Cookie banners, newsletter popups, and chat widgets are removed before the shot; each cleanup step can be turned off.
- Bot checks, blank pages, timeouts, failed loads, and cache hits cost nothing. Responses identify the page verdict and billing status in headers.
- An MCP server gives AI agents tools to take screenshots, inspect page information, and capture PDFs.
- 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000 screenshots. Every feature is on every plan.
Sign up for ScreenshotNeo’s free plan: 1,000 screenshots a month, no card required.
FAQ
Are bwidth and bheight the screenshot’s final pixel dimensions?
They set the browser viewport. The output thumbnail width is controlled separately by width; capture extent is controlled by size.
Can I set a custom viewport on Free?
The documented Free dimensions are fixed at 1280 × 1024. Custom viewport ranges are listed for Gold and Platinum.
Does a larger viewport make the capture full-page?
No. Use size=page for full-page capture where your tier supports it.
Has Thumbalizr’s announced device emulation replaced these parameters?
The Thumbalizr blog announced a transition to ScreenshotCenter and described extended device emulation as planned. That announcement does not establish that the feature is currently available in every Thumbalizr interface. Check current product documentation before depending on it.
