screenshotsage 1.0.0

Official Python SDK for ScreenshotSage - Capture high-quality screenshots of any website

ScreenshotSage Python SDK

Official Python SDK for ScreenshotSage - Capture high-quality screenshots of any website.

Installation

pip install screenshotsage

Quick Start

from screenshotsage import ScreenshotSage

# Initialize the client
client = ScreenshotSage(api_key="your-api-key")

# Basic screenshot
result = client.capture(url="https://example.com")
print(result["data"]["downloadUrl"])

# Mobile screenshot
result = client.capture(
    url="https://example.com",
    devicePreset="mobile",
    format="webp",
    quality=85
)

# Full page screenshot
result = client.capture(
    url="https://example.com",
    fullPage=True,
    format="png"
)

# Download the screenshot
image_bytes = client.download(result["data"]["downloadUrl"])
with open("screenshot.png", "wb") as f:
    f.write(image_bytes)

# Or capture and download in one step
image_bytes = client.capture_and_download(url="https://example.com")

Async Usage

import asyncio
from screenshotsage import ScreenshotSage

async def main():
    async with ScreenshotSage(api_key="your-api-key") as client:
        result = await client.capture_async(url="https://example.com")
        print(result["data"]["downloadUrl"])

        # Download
        image_bytes = await client.download_async(result["data"]["downloadUrl"])

asyncio.run(main())

Features

Device Presets

# Desktop (default: 1200x800)
client.capture(url="https://example.com", devicePreset="desktop")

# Tablet (768x1024)
client.capture(url="https://example.com", devicePreset="tablet")

# Mobile (375x667, iPhone user agent)
client.capture(url="https://example.com", devicePreset="mobile")

Output Formats

# PNG (default)
client.capture(url="https://example.com", format="png")

# JPEG with quality
client.capture(url="https://example.com", format="jpeg", quality=90)

# WebP
client.capture(url="https://example.com", format="webp", quality=85)

# PDF (Professional+ plans)
client.capture(url="https://example.com", format="pdf")

# HTML snapshot
client.capture(url="https://example.com", format="html")

Clean Screenshots

# Remove ads, cookie banners, and chat widgets
client.capture(
    url="https://example.com",
    blockAds=True,
    blockCookieBanners=True,
    blockChatWidgets=True
)

# Hide specific elements
client.capture(
    url="https://example.com",
    hideSelectors=[".popup", "#newsletter-modal", ".sticky-footer"]
)

Geolocation & Timezone

client.capture(
    url="https://maps.google.com",
    geolocation={
        "latitude": 40.7128,
        "longitude": -74.0060,
        "accuracy": 100
    },
    timezone="America/New_York",
    language="en-US"
)

Authentication

# HTTP Basic Auth
client.capture(
    url="https://example.com/admin",
    basicAuth={
        "username": "admin",
        "password": "secret"
    }
)

# Session cookies
client.capture(
    url="https://example.com/dashboard",
    cookies=[
        {
            "name": "session_id",
            "value": "abc123xyz",
            "httpOnly": True,
            "secure": True
        }
    ]
)

Custom CSS/JavaScript

# Inject custom styles and scripts (Professional+ plans)
client.capture(
    url="https://example.com",
    customCss="body { background: #f0f0f0 !important; }",
    customJs="document.querySelector('.popup')?.remove();"
)

Clip Region

# Capture a specific region
client.capture(
    url="https://example.com",
    clip={
        "x": 0,
        "y": 0,
        "width": 800,
        "height": 600
    }
)

Error Handling

from screenshotsage import ScreenshotSage, ScreenshotSageError

client = ScreenshotSage(api_key="your-api-key")

try:
    result = client.capture(url="https://example.com")
except ScreenshotSageError as e:
    print(f"Error: {e}")
    print(f"Status code: {e.status_code}")
    print(f"Response: {e.response}")

Configuration

client = ScreenshotSage(
    api_key="your-api-key",
    base_url="https://screenshotsage.com",  # Custom base URL
    timeout=120.0  # Request timeout in seconds
)

License

MIT