Site to Image Logo
API DocsLogin

Site to Image API

Start Here

Welcome to the Site to Image API!

We've done our best to make every simple and easy to understand. If at any time you have any questions, please don't hesitate to send us a message!

An explanation of the tabs above:

  • API in Detail - This lists each API option in detail. If you need a reference or want to dive deep into understanding what's possible, this is your source.
  • Bash/cURL/wget - If you often use the Mac or Linux command line, or if you have access to something like WSL or Cygwin or Git Bash on Windows, this will show you how to easily use Site to Image from that environment.
  • Node.js - If you write server-side code in Node.js or Electron, this will show you how to make use of Site to Image from that environment.
  • Need something else? - If your favorite programming language or environment is not listed here, and you'd like an example to be written for it, send us a message and we'll get one made for you.

API in Detail

To use the Site to Image API, you must make a GET request to https://sitetoimage.com/api/screenshot with the query parameters described below.

For example:
https://sitetoimage.com/api/screenshot?token=token-3ea1987f0017d0593fcf50d778d4c9d3975a86fa42f0b7228334db8a08d6fe8e&url=https://example.com

Be aware that when images exceed 5 megabytes, the response will be a 302 Found redirect to our CDN, rather than a 200 OK response with the image itself. Please be sure that any tools you are using support redirects. If they don't, setting fileType=jpeg and quality=85 (or smaller) usually produces reasonable file sizes.

  • tokenrequiredYour Site to Image API token.

    To get your API token, click here to go to the Site to Image account details page.
    Example: token-3ea1987f0017d0593fcf50d778d4c9d3975a86fa42f0b7228334db8a08d6fe8e
  • urlrequiredThe URL you'd like to take a screenshot of.

    If the URL contains special characters it may need to be encoded using encodeURIComponent or your programming language's equivalent.
    Example: https://example.com
  • widthoptionalThe width in pixels of the browser window used to produce the screenshot. Defaults to 1920. Minimum is 100, maximum is7680.Example: 800
  • heightoptionalThe height in pixels of the browser window used to produce the screenshot. Defaults to 1080. Minimum is 100, maximum is4320.

    To capture the full height of the page, see the fullPageoption.
    Example: 600
  • fullPageoptionalIf enabled, returns the full content of the page, rather than cutting off at the given height. Can be true orfalse. Defaults to false.

    The resulting image will be as tall as necessary to contain all content. Ifheight is specified in combination with fullPage, the resulting image will be as tall as the content, or as tall asheight, whichever is larger. Note that some websites change behavior based on the browser's reported height, so you may need to specify a particular height even if the full content is always larger, depending on how you want the website to behave.
    Example: true
  • fileTypeoptionalWhat file type to return. Can be "jpeg" or "png" (without quotes). Defaults to jpeg. To control the quality of the resulting jpeg, see thequality option.Example: png
  • qualityoptionalIf fileType is set to jpeg (the default), this controls the quality of the resulting jpeg. Minimum is 1, maximum is 100. Defaults to 85.Example: 70
  • omitBackgroundoptionalMakes the default white background of the browser transparent, resulting in a partially transparent image on many sites. Can be eithertrue or false. Defaults to false.Example: true
  • loadedAutoDetectoptionalA number from 0 through 3 that controls when Site to Image decides that the page has loaded. Defaults to 2. You may wish to combine this option with thedelayMs option. The values mean:
    • 0 - The HTML of the page has been downloaded. Most or all of the other content on the page (images, scripts, CSS, etc.) will not have loaded yet. This corresponds to the DOMContentLoaded event in JavaScript.
    • 1 - The page has had no more than 2 outstanding requests for 500ms. This may mean that not all content has loaded yet. But, it also means that you don't have to wait for the slowest resources on the page to load.
    • 2 - All the resources initially requested by the HTML page have been loaded. This corresponds with the load event in JavaScript.
    • 3 - All network requests initiated by the page have finished, and the page has not made any new requests in 500ms.
    Example: 3
  • delayMsoptionalA number from 0 through 60000 specifying the milliseconds to wait after Site to Image has detected that the page has loaded. Defaults to 0. This is especially useful for sites that have loading animations, scripts that run on load, or that otherwise do not display their content immediately.Example: 1000
  • ttloptionalA number from 0 through 2678400 (31 days) specifying the number of seconds to cache the image for. Defaults to 300 (five minutes). Repeat requests with the same parameters will receive the cached image rather than creating a fresh screenshot. Requests for cached screenshots do not count towards your usage quota.

    If you need to force a new screenshot to be taken, see the unique parameter.
    Example: 3600
  • uniqueoptionalAn arbitrary string of your choosing used to force a fresh screenshot. For example, if you previously took a screenshot and used a large ttl value to keep it cached for a long time, you could vary this parameter to force a fresh screenshot to be taken. The current timestamp is a good choice if you don't have anything in particular that you want to use as a unique value.Example: 1567028300511

Bash

# Find your API token at http://localhost:3000/account
token="token-3ea1987f0017d0593fcf50d778d4c9d3975a86fa42f0b7228334db8a08d6fe8e"
# The URL you want to take a screenshot of:
url="https://example.com"
# The width of the resulting image:
width="800"
# The height of the resulting image:
height="600"
# Whether to capture the full page of content, regardless of the height parameter:
fullPage="false"
# The format to save the image in:
fileType="jpeg"
# The quality of the resulting JPEG:
quality="50"
# Use a transparent background instead of a white one:
omitBackground="true"
# Controls how a page is determined to be "loaded":
loadedAutoDetect="2"
# How long to wait after load before taking the screenshot in milliseconds:
delayMs="1000"
# How long the image should be cached for in seconds:
ttl="300"
# Change this to force a new screenshot to be generated:
unique="1567032458962"
# Use cURL to get the image:
curl -L -G "http://localhost:3000/api/screenshot?token=$token&width=$width&height=$height&fullPage=$fullPage&fileType=$fileType&quality=$quality&omitBackground=$omitBackground&loadedAutoDetect=$loadedAutoDetect&delayMs=$delayMs&ttl=$ttl&unique=$unique" --data-urlencode "url=$url" --output screenshot.jpeg
  % Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
100  236k  100  236k    0     0   114k      0  0:00:02  0:00:02 --:--:--  114k
# Use wget to get the image:
wget "http://localhost:3000/api/screenshot?token=$token&width=$width&height=$height&fullPage=$fullPage&fileType=$fileType&quality=$quality&omitBackground=$omitBackground&loadedAutoDetect=$loadedAutoDetect&delayMs=$delayMs&ttl=$ttl&unique=$unique&url=$url" --output-document=screenshot.jpeg
--2019-08-06 14:20:21--  http://localhost:3000/api/screenshot?token=token-3ea1987f0017d0593fcf50d778d4c9d3975a86fa42f0b7228334db8a08d6fe8e&width=800&height=600&fullPage=false&fileType=jpeg&quality=50&omitBackground=true&url=https://example.com
Resolving sitetoimage.com (sitetoimage.com)... 35.236.94.206
Connecting to sitetoimage.com (sitetoimage.com)|35.236.94.206|:443... connected.HTTP request sent, awaiting response... 200 OK
Length: 15723 (15K) [image/jpeg]
Saving to: ‘screenshot.jpeg’

screenshot.jpeg     100%[===================>]  15.35K  --.-KB/s    in 0s

2019-08-06 14:20:21 (35.7 MB/s) - ‘screenshot.jpeg’ saved [15723/15723]
# The screenshot is now saved in screenshot.jpeg
file screenshot.jpeg
screenshot.jpeg: JPEG image data, JFIF standard 1.01, aspect ratio, density 1x1, segment length 16, baseline, precision 8, 800x600, components 3

Node.js

const querystring = require('querystring');
const https = require('https');
const path = require('path');
const url = require('url');
const fs = require('fs');
const os = require('os');

(async () => {
    try {
        console.info("Making request for screenshot...");
        const imageData = await sitetoimage({
            // Find your API token at http://localhost:3000/account
            token: "token-3ea1987f0017d0593fcf50d778d4c9d3975a86fa42f0b7228334db8a08d6fe8e",
            // The URL you want to take a screenshot of:
            url: "http://example.com",
            // The width of the resulting image:
            width: 800,
            // The height of the resulting image:
            height: 600,
            // Whether to capture the full page of content, regardless of the height parameter:
            fullPage: false,
            // The format to save the image in:
            fileType: "jpeg",
            // The quality of the resulting JPEG:
            quality: 50,
            // Use a transparent background instead of a white one:
            omitBackground: true,
            // Controls how a page is determined to be "loaded":
            loadedAutoDetect: 2,
            // How long to wait after load before taking the screenshot in milliseconds:
            delayMs: 1000,
            // How long the image should be cached for in seconds:
            ttl: 60 * 5,
            // Change this to force a new screenshot to be generated:
            unique: ""
        });
        console.info("Successfully received screenshot!");

        console.info("Writing to disk...");
        const filePath = path.join(os.tmpdir(), 'screenshot-' + Date.now() + '.jpeg');
        fs.writeFileSync(filePath, imageData);
        console.info("Successfully wrote screenshot to " + filePath);
    } catch(e) {
        console.error("Failed to download image.");
        console.error(e);
    }

    console.info("Done.");
})();

/**
 * Returns a Promise for a Buffer containing the screenshot:
 *
 * @param {Object} opts Options for your Site to Image screenshot.
 * @param {String} opts.token Site to Image API token. Find your API token at http://localhost:3000/account
 * @param {String} opts.url The URL you want to take a screenshot of.
 * @param {Number} [opts.width] The width of the resulting image.
 * @param {Number} [opts.height] The height of the resulting image.
 * @param {Boolean} [opts.fullPage] Whether to capture the full page of content, regardless of the height parameter.
 * @param {"jpeg" | "png"} [opts.fileType] The format to save the image in.
 * @param {Number} [opts.quality] The quality of the resulting JPEG.
 * @param {Boolean} [opts.omitBackground] Use a transparent background instead of a white one.
 * @param {Number} [opts.loadedAutoDetect] Controls how a page is determined to be "loaded".
 * @param {Number} [opts.delayMs] How long to wait after load before taking the screenshot in milliseconds.
 * @param {Number} [opts.ttl] How long the image should be cached for in seconds.
 * @param {String} [opts.unique] Change this to force a new screenshot to be generated.
 * @param {Boolean} [opts.redirectRequest] If true, request opts.url directly because we got it from a redirect.
 * @returns {Promise<Buffer>}
 */
function sitetoimage(opts) {
    return new Promise((resolve, reject) => {
        let urlForRequest = "http://localhost:3000/api/screenshot?" + querystring.encode(opts);

        if (opts.redirectRequest) {
            urlForRequest = opts.url;
        }

        const options = url.parse(urlForRequest);
        options.method = "GET";

        const req = https.request(options, (res) => {
            // Follow any redirects:
            if (res.statusCode >= 300 && res.statusCode < 400) {
                sitetoimage({
                    url: res.headers['location'],
                    token: opts.token,
                    redirectRequest: true
                }).then(resolve, reject);
                return;
            }

            const chunks = [];

            res.on('data', (chunk) => {
                chunks.push(chunk);
            });

            res.on('error', (e) => {
                console.error("Error occurred while receiving data:");
                console.error(e);
                reject(e);
            });

            res.on('end', () => {
                const data = Buffer.concat(chunks);

                if (res.statusCode === 200) {
                    resolve(data);
                } else {
                    reject(new Error("Received non-success status " + res.statusCode + " from server. Error was: " + data.toString()));
                }
            });
        });

        req.on("error", (e) => {
            console.error("Error occurred while making request:");
            console.error(e);
            reject(e);
        });

        req.end();
    });
}

Zapier

Site to Image is integrated with Zapier, allowing you to take screenshots whenever a relevant event is triggered in Zapier.

Click here to create a Zapier Zap that uses Site to Image.