To create a website thumbnail with the ScreenshotOne API, send the page URL to the HTTPS /take endpoint and set image_width and/or image_height to the maximum output dimensions. ScreenshotOne preserves the page image’s aspect ratio and keeps the result within those bounds. Choose a normal viewport capture for a standard preview, full_page=true for the whole document, or clipping when you need a particular region.
Choose what the thumbnail should show
Decide the capture area before choosing its output dimensions. A thumbnail of the current browser viewport, an entire long page, and a cropped hero section are different captures; resizing does not change which part of the page is captured.
As an Amazon Associate I earn from qualifying purchases.
| Thumbnail goal | Capture choice | What to expect |
|---|---|---|
| Typical page preview | Default viewport capture | Captures the current viewport, then resizes the image within the specified dimensions. |
| Full-page preview | full_page=true |
Captures the full document. Long pages and lazy-loaded content may require additional rendering adjustments. |
| Hero, card, or other specific area | Clipping coordinates or selector targeting | For coordinate clipping, provide all four values: clip_x, clip_y, clip_width, and clip_height. A selector can be more stable than fixed coordinates when the page layout changes. |
Prepare an API key and keep it private
Create or copy an API key from the relevant ScreenshotOne organization. Use the access key to authenticate API requests; the secret signing key is separate and is used for signing public links or verifying signed webhook payloads. Do not send the secret key as a request parameter.
Recommended Free Tools
- Store the access key in an environment variable or secrets manager rather than source code.
- Make requests over HTTPS. ScreenshotOne warns that HTTP does not encrypt the access key, authorization headers, cookies, or other sensitive request data.
- Do not put an unsigned URL containing the access key in public HTML. If a key is exposed, replace it and update the application configuration.
Make a thumbnail request
The examples below request a thumbnail no larger than 500 × 400 pixels. Replace the target URL and load your access key from a protected environment variable. ScreenshotOne documents GET requests and POST requests with options in a JSON body; the endpoint returns binary image content with a content type appropriate to the requested format.
#1 Best Overall
cURL
export SCREENSHOTONE_ACCESS_KEY="YOUR_API_KEY"
curl -G "https://api.screenshotone.com/take"
-H "X-Access-Key: $SCREENSHOTONE_ACCESS_KEY"
--data-urlencode "url=https://example.com"
--data-urlencode "image_width=500"
--data-urlencode "image_height=400"
-o thumbnail.pngThe output path determines the filename, not necessarily the returned image format. If you request another format, use a matching filename and the corresponding format option supported by ScreenshotOne.
Python with requests
import os
import requests
access_key = os.environ["SCREENSHOTONE_ACCESS_KEY"]
response = requests.get(
"https://api.screenshotone.com/take",
headers={"X-Access-Key": access_key},
params={
"url": "https://example.com",
"image_width": 500,
"image_height": 400,
},
timeout=90,
)
response.raise_for_status()
with open("thumbnail.png", "wb") as image_file:
image_file.write(response.content)Node.js
const accessKey = process.env.SCREENSHOTONE_ACCESS_KEY;
if (!accessKey) throw new Error("Set SCREENSHOTONE_ACCESS_KEY first");
const params = new URLSearchParams({
url: "https://example.com",
image_width: "500",
image_height: "400",
});
const response = await fetch(
`https://api.screenshotone.com/take?${params}`,
{ headers: { "X-Access-Key": accessKey } }
);
if (!response.ok) {
throw new Error(`ScreenshotOne request failed: ${response.status} ${await response.text()}`);
}
const image = Buffer.from(await response.arrayBuffer());
await import("node:fs/promises").then(fs => fs.writeFile("thumbnail.png", image));When to use POST
For larger or more structured requests, POST options as JSON rather than assembling a long query string. For example, the request body for the same basic capture is:
{
"url": "https://example.com",
"image_width": 500,
"image_height": 400
}Send the access key using the documented X-Access-Key header or another protected server-side method supported by the API. ScreenshotOne documents a maximum POST body size of 100 MiB; host large HTML or Markdown inputs and pass them by URL instead of putting them in the request body.
Rank #2
![Free Fling File Transfer Software for Windows [PC Download]](https://m.media-amazon.com/images/I/41Vq6ZqHfjL._SL160_.jpg)
- Intuitive interface of a conventional FTP client
- Easy and Reliable FTP Site Maintenance.
- FTP Automation and Synchronization
Set dimensions, format, and quality
image_width and image_height are maximum bounds, not instructions to stretch an image to an exact shape. If you specify just one dimension, ScreenshotOne computes the other automatically; the aspect ratio is preserved. Set both when the thumbnail must fit within a fixed box, then check how the resulting proportions appear in the actual card or preview.
- Choose a supported output format that suits the destination. The response is binary image data, so save it as a file or stream it rather than treating it as JSON.
- The documented
image_qualityrange is 0–100, with a default of 80. Quality settings apply to supported formats; test the result where it will appear because no one format or quality value suits every use. - If the destination requires a precise aspect ratio, do not assume the API will distort the screenshot to fill it. Plan for possible empty space or crop the result in your application.
Tune full-page and targeted captures
Full-page pages and lazy-loaded content
Set full_page=true when the complete document matters. If lazy-loaded images are missing or animation appears inconsistently, ScreenshotOne documents options including full_page_algorithm=by_sections, scrolling and delay adjustments, and motion reduction. Additional rendering steps can improve capture behavior but may take longer, and the vendor notes that some pages remain difficult to render reliably.
Clip a region or target an element
For coordinate-based clipping, supply all four clip parameters: clip_x, clip_y, clip_width, and clip_height. If the layout can shift between page loads, targeting an element by selector may be more robust than relying on fixed coordinates.
Modify page content before capture
Use hide selectors, custom CSS, or scripts when the thumbnail should omit or alter page elements. URL-encode supplied styles. If a script navigates to another page or reloads the current page, allow enough wait time for the resulting content to render before capture.
Free tools Windows power users keep installed
One-click scans. No signup required.
Or skip the browser setup
ScreenshotNeo is a website screenshot API and MCP server. Its one-call endpoint returns a screenshot or PDF; for this thumbnail example, request a 500 × 400 image:
curl -G "https://api.screenshotneo.com/v1/shot" -d access_key=YOUR_API_KEY --data-urlencode url=https://example.com -o shot.webpSee the ScreenshotNeo API documentation for request options. ScreenshotNeo removes cookie banners, popups, and chat widgets before the shot; bot checks, blank pages, and failed loads are never billed. Its MCP server lets AI agents take screenshots, and 1,000 screenshots a month are free with no card; paid plans start at $5 for 3,000. Sign up for ScreenshotNeo’s free plan.
Troubleshoot common problems
The request fails authentication
Check that the access key belongs to the intended organization, is present in the server-side request, and has not been replaced or revoked. Do not substitute the secret signing key for the API access key.
The saved file is not a usable image
Check the HTTP status before saving the body, as in the Python and Node.js examples. An error response is not image data. Also ensure that your filename extension matches the format actually requested.
The result is the wrong size or shape
Remember that the width and height options are maximum bounds and preserve aspect ratio. Provide both bounds when you need a constrained box, and verify the result in its destination rather than expecting the screenshot to be stretched.
A full-page result misses content
Lazy-loaded elements may need scrolling, a delay, or the by_sections full-page algorithm. Motion reduction may help when animation causes inconsistent captures. More rendering work can increase capture time.
Best Value
A clipped capture is empty or off target
Check that all four clip values are supplied and that the coordinates and dimensions describe the intended region. When page geometry varies, target an element instead of depending on fixed coordinates.
Independent reader supportYour contribution helps us test, update, and keep practical guides available for everyone.Plan for safe, dependable thumbnail delivery
- Keep API calls on a server you control when a request includes a private access key. The Getting Started guide shows API URLs as image sources, but exposing an unsigned key-bearing URL publicly risks disclosing the key.
- Use HTTPS for every request. For sensitive request data, avoid putting credentials or other secrets in a URL that may be logged or exposed.
- Test representative pages, including long pages and pages with lazy-loaded content, using the dimensions, format, and capture scope your application will actually use. The documented options do not establish a universal best configuration or comparative performance benchmark.
- For larger or structured requests, use POST and account for the documented 100 MiB maximum request-body size. For ordinary thumbnail requests, GET is also supported.
Frequently Asked Questions
Can I make a thumbnail with only one dimension set?
Yes. Set only `image_width` or `image_height`; ScreenshotOne computes the other dimension while preserving the aspect ratio.
Does ScreenshotOne’s thumbnail resizing crop the page to the requested shape?
No. The dimensions are maximum bounds and the aspect ratio is preserved. Choose a capture region or handle any final crop in your application.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
