Generating screenshots just requires a single request to the Screenshot Bin API. Here's what it looks like with some popular programming languages:
curl https://api.screenshotbin.com/v1/screenshot \
-u REPLACE_WITH_SECRET_API_KEY: \
-X POST \
-H "Content-Type: application/json" \
-d '{"url":"https://www.example.com"}'
The code snippets above should be enough to get started, but read on for more in-depth documentation!
When you request a screenshot, it'll be immediately handled by a server in our cloud cluster. This server will navigate a headless browser to the specified url, snap a screenshot, and perform any requested post-processing such as image resizing. We'll then return a publicly accessible image url to you.
Images generated by Screenshot Bin will be cached for a configurable amount of time (up to 30 days). Subsequent requsts for the same url and options will immediately return the cached url, and will not count towards your plan.
Our API is a standard REST-ful API that can be accessed using off-the-shelf HTTP clients in any popular programming language. We use built-in HTTP features, like HTTP authentication and status codes, and JSON is returned by all API responses, including errors.
Authenticate your account when using the API by including your secret API key in the request. You can create new API keys on the Account page. Your API keys carry many privileges, so be sure to keep them secret! Do not share your secret API keys in publicly accessible areas such GitHub, client-side code, and so forth.
Authentication to the API is performed via HTTP Basic Auth. Provide your secret API key as the basic auth username value. You do not need to provide a password.
All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.
Our service is highly optimized for speed, but we can only be as fast as the website you are capturing. If a website has large, slow-loading images, we wait for those images to load by default so your screenshot is accurate.
Luckily, you as a developer have control over this trade-off between speed and accuracy. API options like waitUntilEvent, waitUntilSelector, and delay can ensure that all resources have loaded, but may also increase your request time. We encourage you to explore these options and optimize for your use case.
url String ●required | URL of the page to screenshot. Should start with http:// or https:// Example: 'https://www.google.com' |
format String optional | Image file format. Supported types are png or jpeg. Defaults to png |
imgWidth Number optional | Width in pixels of the final image, useful for creating thumbnails. The image height will be determined automatically based on aspect ratio of the original screenshot, which is configurable through viewportWidth and viewportHeight. Defaults to same as viewportWidth |
viewportWidth Number optional | Width in pixels of the viewport when taking the screenshot. Using lower values like 460 can help emulate what the page looks like on mobile devices. Defaults to 1440 |
viewportHeight Number optional | Height in pixels of the viewport when taking the screenshot. Defaults to 900 |
deviceScaleFactor Number optional | Sets device scale factor (basically dpr) to emulate high-res/retina displays. Number from 1 to 4. Defaults to 1 |
delay Number optional | If set, we'll wait for the specified number of milliseconds after the page load event before taking a screenshot. |
waitUntilEvent String optional | Controls when the screenshot is taken as the page loads. Supported events include:
domcontentloaded is the fastest but riskiest option–many images and other asynchronous resources may not have loaded yet. networkidle0 is the safest but slowest option. load is a nice middle ground. Defaults to load. |
waitUntilSelector String optional | If set, we'll wait for the element specified by this selector to become present before taking a screenshot. Example: '.ready-for-screenshot' |
customCss String optional | A string of CSS that will be injected into a <style>tag on the page. Example: .cookie-warning { display: none; } |
userAgent String optional | Overrides the user agent string that the browser sends during a web request. Defaults to Mozilla/5.0 (Macintosh; Intel Mac OS X 10_12_6) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.94 Safari/537.36 |
full Boolean optional | If set to true, we will capture the full height of the page after it has rendered, rather than just the viewport height. Defaults to false |
lazyLoad Boolean optional | When full is enabled, we will attempt to lazy load all images on the page before capturing a screenshot. Set this to false if you don't care about lazy loading and you'll see a minor speed increase. Defaults to true when full is enabled. |
transparency Boolean optional | Hides default white webpage background for capturing screenshots with transparency, only works when format is png Defaults to false |
timeout Number optional | The number of milliseconds to wait for a page load event before taking a screenshot or failing (controlled by failOnTimeout) Defaults to 10000 (10 seconds) |
failOnTimeout Boolean optional | If set to false, we will take a screenshot when timeout is reached instead of failing the request. Defaults to false |
targetSelector String optional | Specifies a specific element to screenshot instead of the full webpage. This can come in handy for webpages with complex layouts where not all page content is visible in the <body> element's bounding box. Incompatible with full option. Example: '.app-container' |
ttl Number optional | Number of seconds to cache the screenshot for. Subsequent requsts for the same url and options will immediately return the cached url, and will not count towards your plan. Defaults to 2592000 (30 days) |
fresh Boolean optional | Ignore any existing cached images and force a fresh screenshot to be taken. Defaults to false |
Successful reqests will return 200 with the following response format:
{
"url": "https://i.screenshotbin.com/i/49e6a2bfeee24ed4816f527ad0eb35e9.png",
"created": 1511587137, // Seconds from unix epoch when image was generated
"expires": 1514179135, // Seconds from unix epoch when image will expire
"fromCache": true, // true if screenshot was loaded from cache
"monthlyQuota": { // Information about your monthly plan
"plan": "Free",
"requestsAllowed": 100,
"requestsUsed": 1,
"requestsRemaining": 99
}
}
Failed reqests will return 4XX or 5XX with the following response format:
{
"status": "error",
"message": "Screenshot failed due to timeout, page did not load before 10000 milliseconds."
}