How to Create Website Thumbnails from URLs with GrabzIt

To create a website thumbnail with GrabzIt, submit the page URL to its URL-to-image API, set the browser viewport with bwidth and bheight, and set the thumbnail dimensions with width and height. Keep the output smaller than the viewport and use the same aspect ratio to avoid distortion. Make the request from your server so your GrabzIt application key is not exposed to browser visitors.

1. Choose the capture route

GrabzIt supports REST requests and language libraries. REST is convenient when you want to make a direct HTTP request; a library may provide helpers suited to your stack. The examples below use REST so the parameters are visible. GrabzIt documents thumbnail examples for several languages and frameworks in its thumbnail guide and API overview.

For a browser-initiated integration, use GrabzIt’s JavaScript API and follow its authorized-domain setup. Do not put a REST application key in client-side JavaScript: GrabzIt warns that doing so exposes the key. See the REST API reference.

2. Set the browser viewport and thumbnail dimensions

The viewport controls how the target page is rendered. The output dimensions control the size of the resulting thumbnail. They solve different problems: a 1366 × 1170 viewport can render a desktop layout, while a 320 × 240 output produces the smaller image used in a card.

Parameter	Purpose	Documented behavior
`bwidth`	Browser viewport width	Default 1366 pixels; documented maximum 10000 pixels.
`bheight`	Browser viewport height	Default 1170 pixels; documented maximum 10000 pixels.
`width`	Output image width	Sets the thumbnail width.
`height`	Output image height	If width is supplied and height is omitted, output height is proportional. If both output dimensions are absent or zero, output dimensions match the final image.
`format`	Output image format	JPG is the documented default. Supported formats include JPG, PNG, WEBP, BMP, and TIFF.

GrabzIt’s thumbnail guidance recommends making the thumbnail smaller than the browser viewport and keeping their ratios aligned. For example, a 4:3 viewport and 320 × 240 output have the same ratio. If you force an unrelated output ratio, the preview can look stretched or squeezed. Parameter limits, including output-height limits that vary by package, are documented in the live REST reference.

3. Make a REST request with cURL

Replace the placeholder key and target URL. URL-encode the target page because URLs may contain query parameters or other characters that have meaning in a request. The command writes the image response to a local file.

curl -G "https://api.grabz.it/convert" \
  --data-urlencode "key=YOUR_APPLICATION_KEY" \
  --data-urlencode "url=https://example.com" \
  --data-urlencode "format=jpg" \
  --data-urlencode "bwidth=1366" \
  --data-urlencode "bheight=1024" \
  --data-urlencode "width=320" \
  --data-urlencode "height=240" \
  -o thumbnail.jpg

The request shape is based on GrabzIt’s documented REST parameters; see its REST API reference. Store the key in server-side configuration or a secret manager. Do not commit it to source control.

4. Request a thumbnail in Python

This example uses the Python standard library. It URL-encodes all parameters, checks for an HTTP error, and saves the response bytes. Set a timeout appropriate to your application and handle errors at the call site.

from urllib.error import HTTPError, URLError
from urllib.parse import urlencode
from urllib.request import urlopen

params = {
    "key": "YOUR_APPLICATION_KEY",
    "url": "https://example.com",
    "format": "jpg",
    "bwidth": "1366",
    "bheight": "1024",
    "width": "320",
    "height": "240",
}
request_url = "https://api.grabz.it/convert?" + urlencode(params)

try:
    with urlopen(request_url, timeout=90) as response:
        image_bytes = response.read()
    with open("thumbnail.jpg", "wb") as image_file:
        image_file.write(image_bytes)
except HTTPError as exc:
    print(f"GrabzIt returned HTTP {exc.code}: {exc.read().decode('utf-8', 'replace')}")
except URLError as exc:
    print(f"Could not reach GrabzIt: {exc.reason}")

Install no extra package for this example. If you use a GrabzIt library instead, follow its current installation and save-method instructions in the official API documentation.

5. Request a thumbnail in Node.js

Node.js provides fetch in current releases. Check the response before writing it as an image so an error response is not mistaken for a valid thumbnail.

import { writeFile } from "node:fs/promises";

const params = new URLSearchParams({
  key: "YOUR_APPLICATION_KEY",
  url: "https://example.com",
  format: "jpg",
  bwidth: "1366",
  bheight: "1024",
  width: "320",
  height: "240",
});

const response = await fetch(`https://api.grabz.it/convert?${params}`);
if (!response.ok) {
  const detail = await response.text();
  throw new Error(`GrabzIt returned HTTP ${response.status}: ${detail}`);
}

await writeFile("thumbnail.jpg", Buffer.from(await response.arrayBuffer()));

6. Choose output format and capture goal

JPG, PNG, and other formats

JPG is GrabzIt’s documented default. Its image documentation recommends PNG when JPG quality is inadequate for a screenshot. PNG can be a suitable choice when text and sharp edges need to remain clear, while the best choice for your product depends on the image and delivery requirements. GrabzIt lists WEBP, BMP, and TIFF as supported image formats too; check the image documentation for current details. The research sources do not establish a universal quality setting or file-size comparison, so compare representative pages from your own use case.

Viewport thumbnail versus full-page image

A thumbnail commonly represents the page as rendered in a chosen viewport. A full-page image aims to include the document beyond the initial viewport. GrabzIt’s REST API uses special -1 values for full-length behavior, but their meaning depends on the parameter: the reference describes -1 for full browser height and for unreduced thumbnail height, and full-page examples set browser height and output dimensions to -1. Do not apply -1 as a universal value; use the parameter-specific instructions in the REST reference and the full-page guide.

Direct response versus asynchronous delivery

A direct request is useful when the caller can wait for the result. For asynchronous delivery, the REST reference documents an optional callback URL. This is useful when your application should receive a completed capture separately from the request. Implement and secure the callback handling according to GrabzIt’s current API documentation.

7. Handle common problems

Symptom	Likely cause	What to do
Key appears in browser source or network requests	A server-side REST credential was used in client-side code.	Move REST calls to your server. If the capture must be initiated in a browser, use GrabzIt’s JavaScript API and configure authorized domains as documented.
Thumbnail looks stretched	Output width and height do not match the viewport’s aspect ratio.	Use matching ratios, such as 1366 × 1024 for the viewport and 320 × 240 for output.
Image is unexpectedly large or not reduced	Output dimensions were omitted or set to zero, which the reference says can make output dimensions match the final image.	Set explicit `width` and `height`, or set width alone when proportional height is desired.
Request fails for very large dimensions	A browser dimension exceeded its documented maximum, or an output limit depends on the account package.	Keep browser dimensions within the documented 10000-pixel maximum and consult the live reference for output-size restrictions.
Downloaded file is an error message, not an image	The client saved an unsuccessful response without checking its status or contents.	Check HTTP status and inspect the response body before writing the file. Log errors without exposing the application key.
Target URL with query parameters is malformed	The URL was concatenated into the request without encoding.	Use `curl --data-urlencode`, Python’s `urlencode`, or JavaScript’s `URLSearchParams`.
Page content is missing from the capture	The rendered viewport or the chosen thumbnail/full-page behavior does not match the intended preview.	Adjust browser width and height to the desired page layout. If the goal is the complete document, use the documented full-page parameters rather than treating an ordinary viewport capture as full-page.

8. Performance, reliability, and cost considerations

Choose only the viewport you need. The viewport affects how responsive layouts render, while output dimensions control the delivered thumbnail size. Use a representative viewport for the layout your preview should show.
Keep the output appropriately small. Thumbnail dimensions should match the destination component and preserve the aspect ratio; this avoids sending unnecessarily large images to a card or list.
Plan for remote-page variability. A URL capture depends on the target page loading and rendering. Handle request failures and timeouts in the calling service, and avoid assuming that every target URL will produce a usable image.
Use asynchronous callbacks when the request flow should not wait. GrabzIt documents a callback URL for asynchronous delivery. Design the receiving endpoint to process completion reliably and to tolerate retry or duplicate notifications if applicable to the integration.
Verify current account limits and pricing before launch. The reviewed sources establish parameter behaviors but do not establish current plans, quotas, or prices. Avoid building a cost estimate from undocumented assumptions; consult GrabzIt’s current product and account information.

Or skip the browser setup

ScreenshotNeo is a website screenshot API and MCP server for developers. Its GET endpoint returns an image or PDF from a URL, and the documented API accepts familiar screenshot API parameter names to make switching easier. See the ScreenshotNeo API documentation.

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

ScreenshotNeo accepts cookie and consent banners before capture and removes more than 60 known consent platforms, newsletter popups, and chat widgets; each step can be turned off. Bot checks and CAPTCHAs, blank pages, timeouts, failed loads, and cache hits are not billed, and responses identify the page verdict and billing status in headers. Its MCP server includes take_screenshot, get_page_info, and capture_pdf for AI agents. The Free plan includes 1,000 screenshots per month with no card; paid plans start at $5 for 3,000 screenshots, and every feature is on every plan.

FAQ

Can I set only the thumbnail width?

Yes. GrabzIt’s REST documentation says that when output width is supplied without output height, the output height is proportional.

Does GrabzIt make a full-page thumbnail?

It supports full-page capture settings, but the special -1 values are parameter-specific. Follow the full-page example and REST reference for the exact parameters.

Which format should I start with?

JPG is the documented default. GrabzIt recommends PNG when JPG quality is not adequate for the screenshot.

Can I call the REST endpoint directly from a public web page?

GrabzIt warns that this exposes the application key. Use server-side REST, or its JavaScript API for browser-side work with the required domain configuration.