Skip to main content
Use the requests library to call the Screenshotly API from Python.

​
Prerequisites

pip install requests

​
Capture a screenshot

import requests
import os

API_KEY = os.environ['SCREENSHOTLY_API_KEY']
API_URL = 'https://api.screenshotly.dev/api/v1/screenshots'

def capture_screenshot(url, **options):
    headers = {
        'screenshotly-api-key': API_KEY,
        'Content-Type': 'application/json'
    }
    payload = {'url': url, **options}

    response = requests.post(API_URL, headers=headers, json=payload)
    response.raise_for_status()
    return response.json()

result = capture_screenshot(
    'https://example.com',
    format='png',
    width=1280,
    height=800
)
print('Screenshot:', result)

​
Full-page capture

result = capture_screenshot(
    'https://example.com',
    fullPage=True,
    format='jpeg',
    quality=80
)

​
Check screenshot status

def get_screenshot(screenshot_id):
    headers = {'screenshotly-api-key': API_KEY}
    response = requests.get(
        f'{API_URL}/{screenshot_id}',
        headers=headers
    )
    response.raise_for_status()
    return response.json()

status = get_screenshot('scr_abc123')
print('Status:', status['status'])
print('URL:', status.get('screenshotUrl'))

​
Error handling

import requests

def capture_screenshot_safe(url, **options):
    headers = {
        'screenshotly-api-key': API_KEY,
        'Content-Type': 'application/json'
    }
    payload = {'url': url, **options}

    try:
        response = requests.post(API_URL, headers=headers, json=payload)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.HTTPError as e:
        print(f'HTTP error: {e} - {e.response.text}')
    except requests.exceptions.ConnectionError as e:
        print(f'Connection error: {e}')
    except requests.exceptions.Timeout as e:
        print(f'Timeout error: {e}')

    return None

​
Batch processing

To capture multiple URLs, loop through them or use Screenshotly’s batch endpoint: 
urls = [
    'https://example.com',
    'https://google.com',
    'https://github.com'
]

for url in urls:
    result = capture_screenshot(url, format='png', width=1280, height=800)
    if result:
        print(f'{url}: captured')

​
Download the screenshot image

def download_screenshot(image_url, output_path):
    response = requests.get(image_url)
    response.raise_for_status()
    with open(output_path, 'wb') as f:
        f.write(response.content)
    print(f'Saved to {output_path}')