How to create website screenshots using Screenshot API

In modern times, people are spending less time reading content and more often skimming the content for the most important things, forgetting about large paragraphs. The era of visual content is here and it’s more important than ever. If you are presenting your users with any kind of links to websites, displaying a portfolio, or maybe showing a chronology of web page design through different iterations, the best way is to create a screenshot of the URL using Screenshot API and insert it directly into your content.

There are a lot of different tools to easily create screenshots from a URL but they are usually lacking automation features like defining the viewport for the webpage or making use of real browsers like Mozilla Firefox or Internet Explorer. By not using real browsers, screenshots from other automation tools can miss important graphical components and won’t accurately reflect what a user would see.

We use real browsers with an easy to use REST API to enable you capture the most accurate screenshots possible for your applications. To help you get started, we have prepared a quick start guide demonstrating how to use the screenshot API in three simple steps.

Step 1 – Generate API access keys

Access keys allow you to connect to our services without sharing your username and password or other sensitive information in your application.

To generate API keys:

  1. You need to sign-in to your account dashboard (
  2. Navigate to the “API Access Keys” area and select “Create API Key”
  3. Add a description to your key and make sure that the “Screenshots v2” service is selected

Step 2 – Send the screenshot request

In this post we will use HTTP Basic Authentication to make requests to the API. It’s also possible to generate “pre-signed URLs” which grant access to the API for specific requests without using basic authentication. To check out this method, please refer to our documentation.

Since we are using the Python library “requests” to send HTTP requests to the server, we’ll use the basic authentication built into the “requests” library which will add the necessary HTTP header for us.

Make sure you have your access key and secret key and substitute them into the sample code. Your next step is to send the request to our server.

To do that, we simply use the get function from the library passing the encoded URL and your API keys.

import requests
import shutil
from base64 import urlsafe_b64encode

target_website = "<the URL or domain name of the website to retrieve the categories for>"

key = "<insert your API key>"
secret_key = "<insert your API secret key>"

# For additional image parameters and possible image sizes
# see:
parameters = {
    'size': '3xlarge',
    'fullpage': True

api_url = "" % urlsafe_b64encode(target_website)

response = requests.get(api_url, auth=(key, secret_key), stream=True, params=parameters)

Step 3 – Parsing the response

The response to a screenshot request is always an image in PNG format. The HTTP status code is used to know if the image is ready for us to use or if it’s being generated. If the image is ready, this demo will save it to a file called “screenshot_demo.png” in the current directory.

status_code = response.status_code

if status_code == 200:
    # Do something with the image response
    print "Saving the screenshot for '%s' to 'screenshot_demo.png'" % target_website
    with open('screenshot_demo.png', 'wb') as image_file:
        shutil.copyfileobj(response.raw, image_file)
elif status_code == 202:
    print "The screenshot image for '%s' is being generated, check again in a few seconds" % target_website
    # The different status codes are covered in the documentation 
    # 401 : Unauthorized - Verify that your access key and secret key are correct
    print "An error occurred: HTTP %d" % status_code

In addition to retrieving the screenshot / image data for a URL, it’s also possible to get metadata about it as JSON. The response contains information such as a link to the image, if the image was successful and when the image was last generated. Here’s an example of what that response looks like:

    "data": [{
        "image": "",
        "state": "READY",
        "updated": "Mon, 30 May 2016 23:13:06 +0000",
        "url": ""

You can read more about this feature in our documentation here:

Interested in trying it yourself?

Signup now, we are offering a free plan that allows you to get started right away with any of our API services.

Create my free account