screenshotapi

Official typed Python SDK for ScreenshotAPI, the hosted screenshot API for turning URLs or HTML into PNG, JPEG, WebP, or PDF captures.

Install

pip install screenshotapi-to

Python 3.8+ is supported. The distribution package is screenshotapi-to, the import package is screenshotapi, and the package ships py.typed metadata for type checkers.

Authentication

Create an API key in the ScreenshotAPI dashboard, then keep it in an environment variable:

export SCREENSHOTAPI_KEY="sk_live_your_key_here"

The SDK sends your key in the x-api-key header. Keep API keys on the server; do not expose them in browser bundles or mobile apps.

First Screenshot

import os

from screenshotapi import ScreenshotAPI

client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])

metadata = client.save(
    {
        "url": "https://example.com",
        "width": 1440,
        "height": 900,
    },
    "screenshot.png",
)

print(f"Screenshot ID: {metadata.screenshot_id}")
print(f"Credits remaining: {metadata.credits_remaining}")

Usage

Initialize the Client

from screenshotapi import ScreenshotAPI

client = ScreenshotAPI(
    "sk_live_your_key_here",
    base_url="https://screenshotapi.to",
    timeout=60.0,
)

Capture Bytes

from screenshotapi import ScreenshotOptions

result = client.screenshot(
    ScreenshotOptions(
        url="https://example.com",
        full_page=True,
        type="webp",
        quality=90,
        color_scheme="dark",
    )
)

image_bytes = result.image
content_type = result.content_type
credits_remaining = result.metadata.credits_remaining

Plain dictionaries are also supported:

result = client.screenshot(
    {
        "url": "https://example.com",
        "full_page": True,
        "type": "webp",
    }
)

Async Capture

import asyncio
import os

from screenshotapi import ScreenshotAPI

client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])


async def main() -> None:
    result = await client.async_screenshot({"url": "https://example.com"})
    print(f"Duration: {result.metadata.duration_ms}ms")

    await client.async_save({"url": "https://example.com"}, "screenshot.png")


asyncio.run(main())

Advanced Options

result = client.screenshot(
    {
        "url": "https://example.com/dashboard",
        "width": 1280,
        "height": 720,
        "device_pixel_ratio": 2,
        "full_page": False,
        "type": "webp",
        "quality": 85,
        "color_scheme": "dark",
        "wait_until": "networkidle0",
        "wait_for_selector": ".ready",
        "delay": 500,
        "block_ads": True,
        "remove_cookie_banners": True,
        "remove_popups": True,
        "remove_elements": [".newsletter", "#cookie-banner"],
        "css_inject": "body { caret-color: transparent; }",
        "js_inject": "window.scrollTo(0, 0)",
        "stealth_mode": True,
        "timezone": "America/New_York",
        "locale": "en-US",
        "cache_ttl": 3600,
        "preload_fonts": True,
        "geo_latitude": 40.7128,
        "geo_longitude": -74.0060,
        "geo_accuracy": 25,
    }
)

HTML rendering uses POST /api/v1/screenshot automatically:

result = client.screenshot(
    {
        "html": "<html><body><h1>Invoice #123</h1></body></html>",
        "type": "pdf",
    }
)

Supported options:

Error Handling

from screenshotapi import (
    AuthenticationError,
    InsufficientCreditsError,
    InvalidAPIKeyError,
    NetworkError,
    ScreenshotAPI,
    ScreenshotAPIError,
    ScreenshotFailedError,
)

client = ScreenshotAPI("sk_live_your_key_here")

try:
    client.screenshot({"url": "https://example.com"})
except AuthenticationError:
    print("Missing API key")
except InvalidAPIKeyError:
    print("Invalid or revoked API key")
except InsufficientCreditsError as exc:
    print(f"No credits remaining. Balance: {exc.balance}")
except ScreenshotFailedError as exc:
    print(f"Screenshot failed: {exc}")
except NetworkError as exc:
    print(f"Could not reach ScreenshotAPI: {exc}")
except ScreenshotAPIError as exc:
    print(f"ScreenshotAPI error {exc.status} ({exc.code}): {exc}")

Examples

Runnable examples live in examples/:

• script_usage.py for one-off scripts and cron jobs
• fastapi_app.py for FastAPI endpoints
• django_view.py for Django views
• flask_app.py for Flask routes

Pricing and Free Tier

ScreenshotAPI includes 200 free screenshots per month with no credit card required. Paid subscriptions and credit packs are available when you need more volume.

Links

• Documentation
• Screenshot API reference
• Pricing
• Support

License

MIT