Code samples


Choose your favorite language, put in your customer API key and you got it!

Complete source code is available on GitHub

#!/bin/bash

CUSTOMER_KEY="PUT_YOUR_CUSTOMER_KEY_HERE"
SECRET_PHRASE="" #leave secret phrase empty, if not needed

URL="https://www.google.com"
DIMENSION="1366x768" # or "1366xfull" for full length screenshot
DEVICE="desktop"
FORMAT="png"
CACHE_LIMIT="0"
DELAY="2000"
ZOOM="100"

ARGS=(
--data-urlencode "key=$CUSTOMER_KEY" \
--data-urlencode "dimension=$DIMENSION" \
--data-urlencode "device=$DEVICE" \
--data-urlencode "format=$FORMAT" \
--data-urlencode "cacheLimit=$CACHE_LIMIT" \
--data-urlencode "delay=$DELAY" \
--data-urlencode "zoom=$ZOOM" \
--data-urlencode "url=$URL"
)

if [[ -n "$SECRET_PHRASE" ]]; then
  HASH=$(echo -n $URL$SECRET_PHRASE | md5sum | cut -d ' ' -f 1)
  ARGS+=(--data-urlencode "hash=$HASH")
fi

curl -Gs "https://api.screenshotmachine.com" "${ARGS[@]}" > output.png

Complete source code is available on GitHub


string customerKey = "PUT_YOUR_CUSTOMER_KEY_HERE";
string secretPhrase = ""; //leave secret phrase empty, if not needed

var options = new Dictionary();
// mandatory parameter
options.Add("url", "https://www.google.com");
// all next parameters are optional, see our webtite screenshot API guide for more details
options.Add("dimension", "1366x768"); // or "1366xfull" for full length screenshot
options.Add("device", "desktop");
options.Add("format", "png");
options.Add("cacheLimit", "0");
options.Add("delay", "200");
options.Add("zoom", "100");

ScreenshotMachine sm = new ScreenshotMachine(customerKey, secretPhrase);

string apiUrl = sm.GenerateScreenshotApiUrl(options);
//use final apiUrl where needed
Console.WriteLine(apiUrl);

//or save screenshot directly
string output = "output.png";
new WebClient().DownloadFile(apiUrl, output);
Console.WriteLine("Screenshot saved as " + output);

Complete source code is available on GitHub


String customerKey = "PUT_YOUR_CUSTOMER_KEY_HERE";
String secretPhrase = "";//leave secret phrase empty, if not needed

ScreenshoMachine sm = new ScreenshoMachine(customerKey, secretPhrase);

Map options = new HashMap();
// mandatory parameter
options.put("url", "https://www.google.com");
// all next parameters are optional, see our website screenshot API guide for more details
options.put("dimension", "1366x768"); // or "1366xfull" for full length screenshot
options.put("device", "desktop");
options.put("format", "png");
options.put("cacheLimit", "0");
options.put("delay", "200");
options.put("zoom", "100");

String apiUrl = sm.generateScreenshotApiUrl(options);
// put link to your html code
System.out.println(apiUrl);

// or save screenshot as an image
URLConnection openConnection = new URL(apiUrl).openConnection();
openConnection.addRequestProperty("User-Agent", "Mozilla/4.0");
InputStream in = openConnection.getInputStream();
String output = "out.png";
Files.copy(in, Paths.get(output), StandardCopyOption.REPLACE_EXISTING);
System.out.println("Screenshot saved as " + output);

See our official npm package. Complete source code is available on GitHub.


// npm install screenshotmachine --save

var screenshotmachine = require('screenshotmachine');

var customerKey = 'PUT_YOUR_CUSTOMER_KEY_HERE';
    secretPhrase = ''; //leave secret phrase empty, if not needed
    options = {
      //mandatory parameter
      url : 'https://www.google.com',
      // all next parameters are optional, see our website screenshot API guide for more details
      dimension : '1366xfull', // or "1366xfull" for full length screenshot
      device : 'desktop',
      format: 'png',
      cacheLimit: '0',
      delay: '200',
      zoom: '100'
    }

var apiUrl = screenshotmachine.generateScreenshotApiUrl(customerKey, secretPhrase, options);

//put link to your html code
console.log('<img src="' + apiUrl + '">');

//or save screenshot as an image
var fs = require('fs');
var output = 'output.png';
screenshotmachine.readScreenshot(apiUrl).pipe(fs.createWriteStream(output).on('close', function() {
  console.log('Screenshot saved as ' + output);
}));

Complete source code is available on GitHub


#!/usr/bin/perl
use strict;
use warnings;
use LWP::UserAgent;
use URI::Escape qw(uri_escape);
use Digest::MD5 qw(md5_hex);

my $base_api_url = 'https://api.screenshotmachine.com/?';

my $customer_key = 'PUT_YOUR_CUSTOMER_KEY_HERE';
my $secret_phrase = ''; # leave secret phrase empty, if not needed

my %options;
# mandatory parameter
$options{'url'} = 'https://www.google.com';
# all next parameters are optional, see our website screenshot API guide for more details
$options{'dimension'} = '1366x768'; # or "1366xfull" for full length screenshot
$options{'device'} = 'desktop';
$options{'format'} = 'png';
$options{'cacheLimit'} = '0';
$options{'delay'} = '200';
$options{'zoom'} = '100';

my $api_url = $base_api_url . 'key=' . $customer_key;
if ($secret_phrase ne "")
{
  $api_url .= '&hash=' . md5_hex($options{'url'} . $secret_phrase);
}
foreach my $key (keys %options)
{
  $api_url .= '&' . $key . '=' . uri_escape($options{$key});
}
# put link to your html code
print "<img src=\"" . $api_url . "\">\n";

# or save screenshot as an image
my $lwp = LWP::UserAgent->new(agent=>'perl-client', cookie_jar=>{});
my $output = 'output.png';
my $resp = $lwp->mirror($api_url, $output);
unless($resp->is_success) {
    print $resp->status_line;
}
print "Screenshot saved as " . $output . "\n";

See our official Composer package. Complete source code is available on GitHub


<?php
$customer_key = "PUT_YOUR_CUSTOMER_KEY_HERE";
$secret_phrase = ""; //leave secret phrase empty, if not needed

$machine = new ScreenshotMachine($customer_key, $secret_phrase);

//mandatory parameter
$options['url'] = "https://www.google.com";

// all next parameters are optional, see our website screenshot API guide for more details
$options['dimension'] = "1366x768";  // or "1366xfull" for full length screenshot
$options['device'] = "desktop";
$options['format'] = "png";
$options['cacheLimit'] = "0";
$options['delay'] = "200";
$options['zoom'] = "100";

$api_url = $machine->generate_screenshot_api_url($options);

//put link to your html code
echo '<img src="' . $api_url . '">' . PHP_EOL;

//or save screenshot as an image
$output_file = 'output.png';
file_put_contents($output_file, file_get_contents($api_url));
echo 'Screenshot saved as ' . $output_file . PHP_EOL;

Complete source code is available on GitHub


customer_key = 'PUT_YOUR_CUSTOMER_KEY_HERE'
secret_phrase = '' # leave secret phrase empty, if not needed
options = {
  'url': 'https://www.google.com', # mandatory parameter
  # all next parameters are optional, see our website screenshot API guide for more details
  'dimension': '1366x768', # or "1366xfull" for full length screenshot
  'device': 'desktop',
  'cacheLimit' : '0',
  'delay' : '200',
  'zoom' : '100'
  }

api_url = generate_screenshot_api_url(customer_key, secret_phrase, options)

#put link to your html code
print('<img src="'  + api_url + '">')

#or save screenshot as an image
opener = urllib.request.build_opener()
opener.addheaders = [('User-agent', '-')]
urllib.request.install_opener(opener)
output = 'output.png'
urllib.request.urlretrieve(api_url, output)
print('Screenshot saved as ' + output);

Complete source code is available on GitHub, brought to you by Tupalo.com guys. Please see also Gem home page


require 'screenshot_machine'

ScreenshotMachine.configure do |config|
  config.key = '012345abcdefg'
end

website_url = "http://google.com/?q=great+gem"
sm = ScreenshotMachine.new(website_url)
# Returns a binary stream of the file
sm.screenshot

Complete source code is available on GitHub


Dim customerKey As String = "PUT_YOUR_CUSTOMER_KEY_HERE"
Dim secretPhrase As String = "" REM leave secret phrase empty, If Not needed

Dim options As New Dictionary(Of String, String)
REM mandatory parameter
options.Add("url", "https://www.google.com")
REM  all next parameters are optional, see our website screenshot API guide for more details
options.Add("dimension", "1366x768") REM or "1366xfull" for full length screenshot
options.Add("device", "desktop")
options.Add("format", "png")
options.Add("cacheLimit", "0")
options.Add("delay", "200")
options.Add("zoom", "100")

Dim sm As ScreenshotMachine = New ScreenshotMachine(customerKey, secretPhrase)
Dim apiUrl As String = sm.GenerateScreenshotApiUrl(options)

REM use final apiUrl where needed
Console.WriteLine(apiUrl)

REM or save screenshot directly
Dim client As New WebClient()
Dim output As String = "output.png"
client.DownloadFile(apiUrl, output)
Console.WriteLine("Screenshot saved as " + output)

API parameters


API is based on HTTP GET request.

All API calls must start with https://api.screenshotmachine.com/? followed by query parameters (field-value pairs) described in the table below. Parameters are separated by an ampersand (&).

Parameter Description
key Unique customer API key is required for using our service. You will get your key after sign up.
url The web page URL you want to capture. Url percent-encoding is strongly recommended and http(s):// protocol prefix is optional.
dimension Size of the web snapshot or webpage screenshot in format [width]x[height]. Default value is 120x90.
width can be any natural number greater than or equals to 100 and smaller or equals to 1920.
height can be any natural number greater than or equals to 100 and smaller or equals to 9999. Also full value is accepted if you want to capture full length webpage screenshot.

Examples:
320x240 - website thumbnail size 320x240 pixels
800x600 - website snapshot size 800x600 pixels
1024x768 - web screenshot size 1024x768 pixels
1920x1080 - webpage screenshot size 1920x1080 pixels
1024xfull - full page screenshot with width equals to 1024 pixels (can be pretty long)

Hint
For capturing full length webpage screenshots consider using delay parameter with greater value, for example delay=2000 or more, because some long pages contains more images or fancy animations.
device You can capture the web page using various devices.There are three options available: desktop, phone, tablet. Default value is desktop.

Hint
For capturing screenshots using typical dimensions on the device you can use these combinations of dimension and device parameters:
device=desktop and dimension=1024x768 - desktop screenshot with size 1024x768 pixels
device=phone and dimension=480x800 - mobile phone screenshot with size 480x800 pixels
device=tablet and dimension=800x1280 - tablet screenshot with size 800x1280 pixels

There are a lot of other combinations here. Just choose one, which is best for you.
format Format of the thumbnail or screenshot. Default value is jpg. Available values are: jpg, png, gif
hash If you are calling our service directly from the public HTML pages, we suggest you to safeguard your account with hash parameter. The hash parameter value is calculated using MD5 algorithm from url parameter value and secret phrase.

PHP code example:

$url = "http://www.google.com";
$secret = "TOP SECRET";
$hash = md5($url.$secret);
Result is: ac502de622959ae5f59a6bdc2346771e

Note: Your secret phrase can be set in your account settings and when you set your secret phrase, all requests with missing or incorrect hash parameter will be ignored.

cacheLimit Allowed values are: (0 - 14)

Using cacheLimit parameter, you can manage how old (in days) cached images do you accept. Default value is 14.

Examples:
cacheLimit=0 : never use cache, always download fresh screenshot
cacheLimit=1 : use image from cache only if is not older than 1 day
cacheLimit=2 : use image from cache only if is not older than 2 days
etc...

Hint
If you need shorter interval than one day, you can use decimal numbers as parameter, e.g. cacheLimit=0.041666 means: use image from cache only if is not older than 1 HOUR. (1/24=0.041666)
delay Allowed values are: (0, 200,400, 600, 800, 1000, 2000, 3000, 4000, 5000, 6000, 7000, 8000, 9000, 10000)

Using delay parameter, you can manage how long capturing engine should wait before the screenshot is created. Default value is 200. This parameter is useful when you want to capture a webpage with some fancy animation and you want to wait until the animation finish.

Examples:
delay=0 : capture website immediately
delay=200 : wait 200ms before capturing
delay=400 : wait 400ms before capturing
etc...
zoom Allowed values are: (10 - 400)

Using zoom parameter, you can manage zoom scale of the webpage before screenshot is captured. Default value is 100 percent. This parameter is useful when you want to capture high resolution screenshot. For example, if you want to capture "retina" website screenshot, set value to 200 or higher.

Examples:
zoom=100 : default zoom factor, original website size
zoom=200 : high resolution screenshot. Final image is 2x bigger than original (zoom=100) screenshot.
zoom=50 : half-size screenshot, 50%

Because of optimization, zoom parameter is ignored for screenshots smaller than typical device dimension mentioned in device parameter description.
click Allowed values:
Any valid CSS selector. More info about selectors can be found in CSS Selector Reference.

Using click parameter you can trigger the "click" event on any HTML element before webpage is captured as screenshot. Useful for accepting annoying GDPR or cookie banners.

Examples:
  • click=.button-close will click on the element with class="button-close" before screenshot is captured
  • click=#button-close (correctly encoded as click=%23button-close) will click on the element with id="button-close" before capturing screenshot
Percent-encoding is strongly recommended, specially while using # character or any others reserved characters.
hide Allowed values:
Any valid CSS selectors separated by comma. More info about selectors can be found in CSS Selector Reference.

Using hide parameter you can hide/remove any HTML element before webpage is captured as screenshot. Useful for hiding various GDPR/cookie banners, popup dialogs or any other web page elements.

Examples:
  • hide=.cookie-banner will hide all elements with class="cookie-banner" before capturing web page screenshot
  • hide=#cookie-banner (correctly encoded as hide=%23cookie-banner) will hide element with id="cookie-banner" before capturing web site screenshot
  • hide=.add-banner1,.add-banner2 will hide all elements with class="add-banner1" or class="add-banner2" before capturing screenshot
Note
Percent-encoding is strongly recommended, specially while using # character or any others reserved characters.
cookies Allowed values:
A semicolon [;] separated list of cookies which should be used for screenshot capturing. Each cookie contains a name-value pair. Multiple pairs must be separated by a semicolon. Percent-encoding is required.

Example:
Cookies data name1=value1;name2=value2 must be encoded into format name1%3Dvalue1%3Bname2%3Dvalue2.
accept-language Sets the Accept-Language header on request to the web page you want to capture. Using this parameter you can capture screenshot of webpage with a specific language. Percent-encoding is required when using reserved characters.

Example:
en-US
user-agent Sets the User-Agent header on request to the web page you want to capture. Using this parameter you can emulate a specific device. Percent-encoding is required when using reserved characters.

Example:
Mozilla/5.0 (Linux; Android 10; SM-G981B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/80.0.3987.162 Mobile Safari/537.36 will emulate Samsung Galaxy S20 mobile phone.
selector Allowed values:
Any valid CSS selector. More info about selectors can be found in CSS Selector Reference.
Using selector parameter you can capture screenshot of single DOM element.

Example:
table.table:nth-child(3) > tbody:nth-child(2) > tr:nth-child(15)
crop Allowed format:
x,y,width,height in pixels(px)
Using crop parameter you can capture screenshot of the selected region.

Example:
100,0,800,300 captures a screenshot of rectangle with dimension width=800px, height=300px and with upper left corner started at position x=100px and y=0px of the viewport.

Error Handling


Oops, sometimes bad things happens in the universe.

If your API call is invalid or incomplete, you got an error image with text error message. All these error responses also contains our custom HTTP response header field, named X-Screenshotmachine-Response which contains specific error code.

Example:
X-Screenshotmachine-Response: invalid_url

Customers with premium account can upload their custom error images in profile settings.

Error code Description Error image
invalid_hash Provided hash is invalid. invalid hash
invalid_key Specified customer key is invalid. invalid key
invalid_url Specified URL is invalid or authorization is required (401 Unauthorized status code was sent).
See Basic_access_authentication for more info.
invalid url
missing_key Customer key is missing in your request. missing key
missing_url URL parameter is missing in your request. missing url
no_credits Your account is exhausted, you need/should to buy more fresh screenshots. no credits
invalid_selector Specified CSS selector is invalid. system error
invalid_crop Specified crop region is invalid. system error
system_error Generic system error. system error