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:
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.
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.
token-6a5e01c336dc5ec721668e2c862e43d22cce22acc6ed53b98466ee15b626d894
https://example.com
1920
. Minimum is 100
, maximum is7680
.Example: 800
1080
. Minimum is 100
, maximum is4320
.fullPage
option.Example: 600
height
. Can be true
orfalse
. Defaults to false
.height
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
quality
option.Example: png
85
.Example: 70
true
or false
. Defaults to false
.Example: true
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.3
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
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.unique
parameter.Example: 3600
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
# Find your API token at https://sitetoimage.com/account
token="token-6a5e01c336dc5ec721668e2c862e43d22cce22acc6ed53b98466ee15b626d894"
# 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 "https://sitetoimage.com/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 "https://sitetoimage.com/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-- https://sitetoimage.com/api/screenshot?token=token-6a5e01c336dc5ec721668e2c862e43d22cce22acc6ed53b98466ee15b626d894&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
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 https://sitetoimage.com/account
token: "token-6a5e01c336dc5ec721668e2c862e43d22cce22acc6ed53b98466ee15b626d894",
// 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 https://sitetoimage.com/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 = "https://sitetoimage.com/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();
});
}
Site to Image is integrated with Zapier, allowing you to take screenshots whenever a relevant event is triggered in Zapier.