getsnap

Official Python SDK for getSnap.dev — Screenshot & PDF API.

Zero dependencies. Uses only Python's standard library (urllib).

Installation

pip install getsnap

Quick Start

from getsnap import GetSnap

snap = GetSnap("sk_live_YOUR_KEY")

# Take a screenshot
result = snap.screenshot(url="https://github.com", format="png")
print(result["url"])  # CDN URL to your screenshot

Features

• Zero external dependencies (uses urllib)
• Python 3.8+
• Screenshot capture (URL or HTML)
• Binary response (raw image bytes)
• Batch capture (up to 100 URLs)
• Usage tracking
• All API parameters supported: lazy_load, wait_for_selector, hide_selectors, remove_selectors, extract_text, extract_html, click_selector, scroll_to_selector, and more

API

GetSnap(api_key, base_url=None)

Create a client instance.

• api_key — Your getSnap.dev key (starts with sk_live_ or sk_test_)
• base_url — Custom base URL (default: https://api.getsnap.dev)

snap.screenshot(**kwargs)

Take a screenshot. Returns a dict with url, cached, request_id, and optionally extracted_text/extracted_html.

result = snap.screenshot(
    url="https://example.com",
    format="png",
    full_page=True,
    remove_popups=True,
    lazy_load=True,
    extract_text=True,
)
print(result["url"])
print(result["extracted_text"])

snap.screenshot_binary(**kwargs)

Get raw image/PDF bytes.

data = snap.screenshot_binary(url="https://example.com", format="webp", quality=90)
with open("screenshot.webp", "wb") as f:
    f.write(data)

snap.og_image(url, **kwargs)

Generate a 1200x630 Open Graph / Twitter Card image from any URL. Applies social-share-optimized defaults on the server side (PNG, hi-DPI, wait for network idle, block popups + ads). Same billing as screenshot(): 1 credit per fresh capture, 0 credits for cache hits.

result = snap.og_image(url="https://blog.example.com/why-rust")
print(result["url"])  # drop into <meta property="og:image">

All defaults are overrideable via kwargs (viewport_width, viewport_height, format, device_scale_factor, wait_for_selector, extra_delay_ms, block_ads, remove_popups, dark_mode, css). Pass response_type="binary" to get raw bytes with Cache-Control: public, max-age=604800, immutable instead of a JSON URL.

snap.batch(urls, **kwargs)

Capture multiple URLs in one request.

result = snap.batch(
    urls=["https://github.com", "https://stripe.com", "https://vercel.com"],
    format="png",
    remove_popups=True,
)

print(f"{result['succeeded']}/{result['count']} captured")
for r in result["results"]:
    print(f"{r['source_url']} -> {r['url']}")

snap.usage()

Check current usage and quota.

usage = snap.usage()
print(f"{usage['used']}/{usage['limit']} ({usage['plan']})")

snap.referrals()

Get your referral code, ready-to-share URL, reward tier, and aggregated stats. Every getSnap.dev account has a unique code auto-generated at signup - no opt-in required. When someone signs up through your referral URL and pays their first invoice, your Stripe balance is credited by the configured amount (default $5.00).

r = snap.referrals()
print(r["referral_url"])
# https://getsnap.dev/?ref=USERABC1

paid   = r["stats"]["paid"]
earned = r["stats"]["total_earned_cents"] / 100
print(f"{paid} paid conversions, earned ${earned:.2f} lifetime")

snap.diff(before, after, **kwargs)

Visual regression diff between two URLs. Captures both at identical dimensions, compares pixel-by-pixel with pixelmatch, returns before/after/diff CDN URLs plus a similarity score (0-100).

Billed at 2 credits per fresh diff (1 per captured page). Cache hits on either side reduce the charge.

r = snap.diff(
    before={"url": "https://staging.example.com/pricing"},
    after={"url":  "https://example.com/pricing"},
)

print(f"Similarity: {r['similarity']:.2f}%")
if r["similarity"] < 99:
    print(f"{r['changed_pixels']} pixels changed:")
    print(f"  Review: {r['diff_url']}")

Per-side overrides for slower-loading pages:

r = snap.diff(
    before={
        "url": "https://staging.example.com",
        "wait_for_selector": "#pricing-table",
        "extra_delay_ms": 500,
    },
    after={"url": "https://example.com"},
    viewport_width=1440,
    threshold=0.05,  # more sensitive than default 0.1
)

snap.status(request_id)

Check status of an async (webhook) request.

status = snap.status("req_abc123")

Error Handling

from getsnap import GetSnap, GetSnapError

snap = GetSnap("sk_live_YOUR_KEY")

try:
    snap.screenshot(url="https://example.com", format="png")
except GetSnapError as e:
    print(e.status, e.error, str(e))
    # 402, "quota_exceeded", "Monthly limit reached..."

License

MIT