API guide

Our thumbnails capturing service is based on HTTP GET requests.

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

Complete request scheme:

Parameters description

Parameter Type Mandatory Description
key String Yes Unique customer key is required for using our service. You will get your key after sign up.
url String Yes The web page URL you want to capture. Url encoding is recommended and http(s):// protocol prefix is optional.
dimension String No Size of the thumbnail or 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 lenght screenshot.

320x240 - screenshot size 320x240 pixels
800x600 - screenshot size 800x600 pixels
1024x768 - screenshot size 1024x768 pixels
1920x1080 - screenshot size 1920x1080 pixels
1024xfull - full page screenshot with width equals to 1024 pixels (can be pretty long)
device String No You can capture the web page using various devices.There are three options available: desktop, phone, tablet. Default value is desktop.


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 String No Format of the thumbnail or screenshot. Default value is jpg. Available values are: jpg, png, gif
hash String No 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 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 Decimal
(0 - 14)
No Using cacheLimit parameter, you can manage how old (in days) cached images do you accept. Default value is 14.

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


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)
timeout Integer
(0, 200,400, 600, 800, 1000, 2000, 3000, 4000, 5000)
Using timeout 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.

timeout=0 : capture webpage immediately
timeout=200 : wait 200ms before capturing
timeout=400 : wait 400ms before capturing


String No

Use "dimension" parameter instead of "size" parameter.

Size of the thumbnail or screenshot. Default value is T. You can choose from these available sizes:
T: (120 x 90px) - tiny
S: (200 x 150px) - small
E: (320 x 240px) - seminormal
N: (400 x 300px) - normal
M: (640 x 480px) - medium
L: (800 x 600px) - large
X: (1024 x 768px) - extra large
F: full page, complete page from the top to the bottom

The mobile device screen resolutions are also available. You can capture a webpage using mobile phone's screen resolution.
There are two options available:

Nmob: (480 x 800px) - normal
Fmob: full page, complete page from the top to the bottom


(Let's assume, your customer key is 12345)

1) Capture the tiny size (default) thumbnail of http://google.com

2) Capture the full page screenshot of http://google.com in PNG format

3) Capture the extra large (1024 x 768px) screenshot of http://google.com using secret phrase Hello in JPG (default) format

Ruby example

This simple gem is brought you by smart guys from Tupalo.com
ruby example

Error handling

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.

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 URLs. no credits
unsupported Free account owners are not allowed to call our API using HTTPS protocol. unsupported
system_error Generic system error. Oops, sometimes bad things happens in the universe:( system error