pythonsdk

An official Python SDK for ScreenshotOne.com API to take screenshots of URLs, render HTML as images and PDF.

It takes minutes to start taking screenshots. Just sign up to get access and secret keys, import the client, and you are ready to go.

See the screenshot API options for option descriptions and supported values.

Pass access_key to Client and use .async_option(True) for the API's async option. Repeated options such as .proxy_bypass_hosts(["cdn.example.com", "cdn.*.screenshotone.com"]) accept lists.

Installation

pip install screenshotone

Usage

Generate a screenshot URL without executing the request. Or download the screenshot. It is up to you:

import shutil
from screenshotone import Client, TakeOptions

# create API client
client = Client('<your access key>', '<your secret key>')

# set up options
options = (TakeOptions.url('https://screenshotone.com')
    .format("png")
    .viewport_width(1024)
    .viewport_height(768)
    .block_cookie_banners(True)
    .block_chats(True))

# generate the screenshot URL and share it with a user
url = client.generate_take_url(options)
# expected output: https://api.screenshotone.com/take?url=https%3A%2F%2Fscreenshotone.com&viewport_width=1024&viewport_height=768&block_cookie_banners=True&block_chats=True&access_key=<your access key>&signature=6afc9417a523788580fa01a9f668ea82c78a9d2b41441d2a696010bf2743170f

# or render a screenshot and download the image as stream
image = client.take(options)

# store the screenshot the example.png file
with open('example.png', 'wb') as result_file:
    shutil.copyfileobj(image, result_file)

How to handle errors

Read about how to handle the ScreenshotOne API errors, and that's how you can get the HTTP status code and the error code of the request:

from screenshotone import APIErrorException, InvalidRequestException

try:
    # ...
    # render a screenshot and download the image as stream
    image = client.take(options)
    # ...
except InvalidRequestException as e:
    print(f"Invalid request: {e}")
    if e.http_status_code:
        print(f"HTTP Status Code: {e.http_status_code}")
    if e.error_code:
        print(f"Error Code: {e.error_code}")
except APIErrorException as e:
    print(f"API Error: {e}")
    if e.http_status_code:
        print(f"HTTP Status Code: {e.http_status_code}")
    if e.error_code:
        print(f"Error Code: {e.error_code}")
except Exception as e:
    # handle any other exceptions
    print(f"An unexpected error occurred: {e}")

InvalidRequestException inherits from APIErrorException. Catch APIErrorException to handle both; place an InvalidRequestException handler first if you want to handle invalid requests separately.

Development

Install the SDK and run the offline regression tests:

python -m pip install -e .
python -m unittest discover -s tests -v

The tests mock HTTP requests and do not require API keys or network access. tests/fixtures/documented_options.json contains a saved documentation snapshot and its verification date. These tests check the snapshot, not the live docs; refresh it when synchronizing the SDK with the docs.

CI runs the tests on pushes and pull requests using Python 3.7 through 3.14. The release workflow also runs the tests before publishing.

Release

Github Actions is used to automate the release process and publishing to PyPI. Update the library version in pyproject.toml and create a new release to launch the publish workflow.

Useful resources

Python tutorials from the ScreenshotOne blog:

• Take website screenshots with Python
• How to Take Bulk Screenshots in Python with a Screenshot API
• How to Take Website Screenshots with Playwright in Python
• How to Take Full Page Screenshots with Playwright in Python
• How to Take Bulk Screenshots with Playwright in Python
• Website Screenshots with Selenium in Python
• How to Take Screenshots with pyppeteer in Python

License

screenshotone/pythonsdk is released under the MIT license.