API Features

Full-Height Captures

By default, screenshots are rendered based on the height of the selected (or default) viewport. Alternatively, you can request the full height of the target website to be captured, simply by setting the API's fullpage parameter to 1.

Example query:

By default, the screenshotlayer API returns a snapshot of your target website at its original size (1:1). If you'd like to request a thumbnail, append the API's width parameter with your preferred thumbnail width in pixels.

Example query:

The screenshotlayer API's default viewport setting is 1440x900. You can specify a custom viewport by setting the viewport parameter to your desired dimensions. (format: width x height, in pixels)

Example query:

Find below a list of the most commonly used viewport sizes:

Common Viewports:

Your snapshots can be requested in three different formats: PNG, JPG and GIF. You can change the default format (PNG) by simply appending the API's format parameter with your preferred format.

Example query:

Please Note: Output formats are not case sensitive, and appending "JPEG" is just as valid "JPG".

URL Encryption

For those of you who have to display API request URLs on your website (e.g. inside an <img src="..."> tag, it is crucial to make use of the screenshotlayer API's URL Encryption method, which lets you generate a unique Secret Key for every API request and simply append it to the respective query URL.

In order to prevent your publicly displayed API request URL from being abused, you need to follow these steps:

Step 1: Define your target website's URL

First of all, define the URL of the website you want to take a snapshot of.

In our example, we will use the following URL:

A secret keyword can be any secret word or phrase of your choice. As the next step, make sure you have defined it in your account dashboard. If not, you can simply add a secret keyword here.

In our example, we will use the following secret keyword:

Now you will need to combine these two parts (URL & secret keyword) into one, resulting in:

Step 4: Generate your md5 Secret Key

Finally, create an md5 hash of the combined parts. (this will be your secret_key)

Now that you have your Secret Key, you can simply append to your query URL using the API's secret_key parameter and rest assured that your API access is - as long as you'll keep your secret keyword secret - safe from abuse.

Syntax:

The Screenshotlayer API enables you to inject a custom CSS stylesheet into the target website by appending an existing CSS file URL to the API's css_url parameter.

For our example, we have prepared a file called css_inject.css, containing the following CSS declaration:

Example query:

The API's delay parameter enables you to specify a custom delay time (in seconds) before the snapshot is captured. This feature may especially useful if certain contents of your target website appear after the initial page load. (e.g. CSS animations, JavaScript effects)

Example query:

The following query sets a 3-second delay to capture any delayed/animated content on the target website. (http://tumblr.com)

Please Note: The maximum supported delay time is 20 seconds.

TTL (Caching Time)

By default, website screenshots are cached for 30 days (2,592,000 seconds). Using the API's ttl parameter, you can specify a custom caching time (time-to-live) lower than the default setting.

Example query:

The following query requests the snapshot's ttl to be set to 259,200 seconds (3 days).

Please Note: The default ttl (30 days, or 2,592,000 seconds) is the maximum supported caching time.

Force Refresh

You can easily force the API to capture a fresh screenshot of the requested target URL by appending the force parameter to the request URL and setting it to 1.

Example query:

Placeholder image

For the very few seconds a freshly captured screenshot loads, there are two options for requesting a placeholder image:

Option 1: Using the default placeholder

By appending the API's placeholder parameter and setting it to 1, you can request the default screenshotlayer placeholder image, which looks like this:

Option 2: Setting a custom placeholder image URL

If you prefer setting your own custom placeholder image, simply append it to the API's placeholder parameter as an image URL.

Supported file formats: PNG, JPEG, GIF

Example query: (using option 1)

Please Note: If activated, placeholder images are returned immediately after the API request and remain visible until the respective page is refreshed.

Retina/2× Resolution Support

Modern screens — especially on mobile devices and Apple hardware — have very high pixel densities. A screenshot that looks sharp on a regular monitor can appear blurry on a Retina/HiDPI display.

With the Retina/2× resolution option, users will be able to generate images that:

• Appear crisp on modern devices
• They are suitable for embedding in high-end web apps or reports
• Can be printed or zoomed without quality loss

API Parameter

Example API call:

API Example: Full Request (Retina):

WebP Format Support

Screenshotlayer now supports generating screenshots in WebP, a modern image format developed by Google. WebP provides smaller file sizes while maintaining high visual quality, making it an excellent choice for web performance optimization.

• Smaller file sizes: 25–35% reduction compared to PNG and JPEG.
• Transparency support: Like PNG.
• Efficient compression: Like JPEG.
• Broad browser compatibility: Supported in ~95% of browsers worldwide, including Chrome, Edge, Firefox, and Safari.

Feature Specification

New API Parameter

NOTE: 

• Free Plans: WebP quality supports up to 70 by default.

• Paid Plans: WebP quality supports up to 70 by default, up to 100 with a customized quality parameter.

HTTP User-Agent Headers

By default, the screenshotlayer API does not send any HTTP User-Agent headers with your request. You can specify a custom user-agent string by appending it to the API's user_agent parameter.

Example query:

The following query requests a screenshot of http://facebook.com on mobile Safari (iOS 8.0.2, iPhone):

Common User-Agent Strings:

You can find a full list of user-agent strings here.

HTTP Accept-Language Headers

The default HTTP Accept-Language header is en-US, en (US English, or English in general). You can specify a custom Accept-Language header by appending it to the API's accept_lang parameter.

Example query:

The following query requests a screenshot of http://facebook.com in Spanish:

You may also specify several different languages at once. Each additional language is separated by a comma. The order in which the values appear in the header determines the hierarchy of importance.

In the following example,e es-MX (Spanish, Mexico) is the highest priority, followed by general Spanish and general English:

Common Accept-Language Strings:

You can find a comprehensive list of accept-language strings here.

Export to AWS S3

If you are subscribed to the Professional or Enterprise Plan, you may request the API to export your snapshot to your AWS S3 Bucket directly. This can be done simply by appending your S3 Bucket path (format: s3://API_KEY:API_SECRET@bucket) to the API's export parameter.

Example query:

Find below an example query requesting the API to export a screenshot of http://tumblr.com directly to a specified AWS S3 Bucket.

Important: Uploading your snapshot to the given S3 path may take up to 1 minute to complete. Please be aware that our system can only attempt accessing the specified export path and cannot notify you in case your upload fails.

Export to FTP

Professional and Enterprise Customers may also specify a custom ftp path to directly export captured snapshots to. This can be achieved simply by appending your desired FTP path (format: ftp://user:password@server) to the API's export parameter.

Example query:

Find below an example query requesting the API to export a screenshot of http://tumblr.com directly to a specified FTP path.

Important: Uploading your snapshot to the given FTP path may take up to 1 minute to complete. Please be aware that our system can only attempt accessing the specified export path and cannot notify you in case your upload fails.