snaprender

Official Python SDK for the SnapRender Screenshot API. Capture pixel-perfect screenshots, extract page content, run batch jobs, and manage webhooks with a single library.

200 free screenshots/month. Get your API key

Features

• Multiple output formats : PNG, JPEG, WebP, and PDF
• Three input modes : URL, raw HTML, or Markdown
• Signed URLs : generate pre-signed screenshot URLs (no API key needed at render time)
• Content extraction : pull Markdown, plain text, HTML, article, links, or metadata from any page
• Batch screenshots : capture up to 50 URLs in a single job
• Webhooks : receive real-time notifications for screenshot and quota events
• Device emulation : iPhone, iPad, Pixel, and more presets
• Dark mode : capture pages with prefers-color-scheme: dark
• Ad blocking : remove ads automatically before capture
• Cookie banner removal : clean screenshots without consent popups
• Smart caching : configurable CDN cache with TTL control
• Full-page captures : screenshot the entire scrollable page

Install

pip install snaprender

Quick Start

from snaprender import SnapRender

snap = SnapRender(api_key="sk_live_...")

# Capture by URL
image = snap.capture("https://example.com")
with open("screenshot.png", "wb") as f:
    f.write(image)

# Capture from raw HTML
image = snap.capture(html="<h1>Hello World</h1>")

# Capture from Markdown
image = snap.capture(markdown="# Hello World\nSome **bold** text.")

Cache is OFF by default. Every request captures a fresh screenshot. To save credits on repeated requests, pass cache=True. Cached hits are free and return in under 200ms:

image = snap.capture("https://example.com", cache=True)

Context Manager

with SnapRender(api_key="sk_live_...") as snap:
    image = snap.capture("https://example.com")

The HTTP connection is closed automatically when the block exits.

API Reference

Constructor

SnapRender(api_key, base_url="https://app.snap-render.com", timeout=60.0)

snap.capture(url, *, html, markdown, **options) -> bytes | dict

Take a screenshot. Provide exactly one of url, html, or markdown.

• When url is provided alone, the request is sent as GET with query parameters.
• When html or markdown is provided, the request is sent as POST with a JSON body.
• Returns raw image bytes by default. Set response_type="json" to get a dict with metadata and a base64 data URI.

# URL with options
jpg = snap.capture(
    "https://example.com",
    format="jpeg",
    width=1920,
    height=1080,
    full_page=True,
    dark_mode=True,
    quality=95,
)

# HTML input
png = snap.capture(html="<h1 style='color:red'>Red Title</h1>", width=800)

# Markdown input
png = snap.capture(markdown="# Report\n\n| Col A | Col B |\n|-------|-------|\n| 1 | 2 |")

# JSON response (base64 data URI + metadata)
result = snap.capture("https://example.com", response_type="json")
print(result["image"])  # data:image/png;base64,...

Options

snap.sign(url, *, expires_in, **options) -> dict

Generate a signed URL that can be used without an API key. Signing itself is free and does not count against your quota. One credit is consumed when the signed URL is rendered.

result = snap.sign(
    "https://example.com",
    expires_in=3600,       # optional, seconds until expiry
    format="png",
    width=1280,
    dark_mode=True,
)
print(result["signed_url"])   # use this in <img> tags, emails, etc.
print(result["expires_at"])   # ISO 8601 timestamp

Options

Returns { "signed_url": str, "expires_at": str, "expires_in": int }

snap.extract(url, *, type, **options) -> dict

Extract content from a web page. Six extraction types are available:

# Extract as Markdown
result = snap.extract("https://example.com", type="markdown")
print(result["content"])
print(result["wordCount"])

# Extract just the article body
article = snap.extract("https://example.com/blog/post", type="article")

# Extract metadata
meta = snap.extract("https://example.com", type="metadata")

# Scope extraction to a specific element
result = snap.extract(
    "https://example.com",
    type="text",
    selector="#main-content",
    max_length=5000,
)

Options

Returns { "url": str, "type": str, "content": ..., "wordCount": int, "processingTimeMs": int }

snap.batch(urls, **options) -> dict

Create a batch screenshot job for 1 to 50 URLs. The call returns immediately with a job ID. Each URL consumes one credit; credits for failed URLs are rolled back.

job = snap.batch(
    ["https://example.com", "https://example.org", "https://example.net"],
    format="png",
    width=1280,
    dark_mode=True,
)
print(job["job_id"])  # use this to poll status

Options: same screenshot options as capture() (except url, html, markdown, response_type, cache, cache_ttl). These options apply to every URL in the batch.

Returns { "job_id": str, "status": str, "total": int, ... }

snap.get_batch_status(job_id) -> dict

Poll the status of a batch job. Keep polling until status is "completed" or "failed".

import time

job = snap.batch(["https://example.com", "https://example.org"])

while True:
    status = snap.get_batch_status(job["job_id"])
    print(f"{status['status']} - {status.get('completed', 0)}/{status['total']}")
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(2)

# Download results
for result in status["results"]:
    print(result["url"], result["download_url"])

snap.create_webhook(url, events) -> dict

Register a webhook endpoint to receive event notifications. Maximum 5 webhooks per account.

Available events: screenshot.completed, quota.warning, quota.exceeded

webhook = snap.create_webhook(
    url="https://yoursite.com/webhooks/snaprender",
    events=["screenshot.completed", "quota.warning"],
)
print(webhook["id"])
print(webhook["secret"])  # save this for signature verification

snap.list_webhooks() -> list[dict]

List all webhooks registered on your account.

webhooks = snap.list_webhooks()
for wh in webhooks:
    print(wh["id"], wh["url"], wh["events"])

snap.delete_webhook(webhook_id) -> None

Delete a webhook by its ID.

snap.delete_webhook("wh_abc123")

snap.test_webhook(webhook_id) -> dict

Send a test payload to a webhook endpoint. Useful for verifying your handler works before relying on real events.

result = snap.test_webhook("wh_abc123")
print(result)  # delivery status

SnapRender.verify_webhook_signature(payload, signature, secret) -> bool

Static method. Verify the HMAC-SHA256 signature of an incoming webhook payload. Use this in your webhook handler to confirm the request was sent by SnapRender.

from snaprender import SnapRender

# In your webhook handler (e.g., Flask)
@app.route("/webhooks/snaprender", methods=["POST"])
def handle_webhook():
    payload = request.get_data(as_text=True)
    signature = request.headers.get("X-Signature")
    secret = "whsec_..."  # from create_webhook response

    if not SnapRender.verify_webhook_signature(payload, signature, secret):
        return "Invalid signature", 403

    event = request.get_json()
    print(event["type"], event["data"])
    return "OK", 200

snap.info(url) -> dict

Check if a screenshot is cached for a given URL, without capturing it. No credits are consumed.

info = snap.info("https://example.com")
print(info["cached"])      # True or False
print(info["expires_at"])  # ISO timestamp (when cached)

Returns { "url": str, "cached": bool, "cache_key": str | None, "cached_at": str | None, "expires_at": str | None, "content_type": str | None }

snap.usage() -> dict

Get the current billing period's usage summary.

usage = snap.usage()
print(f"{usage['used']}/{usage['limit']} screenshots used")
print(f"Plan: {usage['plan']}, Remaining: {usage['remaining']}")

Returns { "plan": str, "used": int, "limit": int, "remaining": int, "period": dict }

snap.usage_daily(days=30) -> dict

Get a day-by-day usage breakdown.

daily = snap.usage_daily(days=7)
for day in daily["daily"]:
    print(day["date"], day["count"])

LangChain Integration

Use SnapRender as a LangChain tool for AI agents:

import os
from langchain_core.tools import tool
from snaprender import SnapRender

client = SnapRender(api_key=os.environ["SNAPRENDER_API_KEY"])

@tool
def take_screenshot(url: str, format: str = "png", dark_mode: bool = False) -> str:
    """Capture a screenshot of any website URL. Returns base64 data URI."""
    result = client.capture(
        url, format=format, dark_mode=dark_mode, response_type="json"
    )
    return result["image"]

Works with LangGraph, CrewAI, and any framework that supports LangChain tools.

Error Handling

All API errors raise SnapRenderError with code, status, and a human-readable message.

from snaprender import SnapRender, SnapRenderError

snap = SnapRender(api_key="sk_live_...")

try:
    snap.capture("https://example.com")
except SnapRenderError as e:
    print(e.code)    # "QUOTA_EXCEEDED"
    print(e.status)  # 429
    print(e)         # "Monthly quota exceeded"

Common error codes: INVALID_API_KEY, QUOTA_EXCEEDED, INVALID_URL, VALIDATION_ERROR, SCREENSHOT_FAILED.

Links

• Documentation
• Pricing
• Dashboard
• Blog
• GitHub

License

MIT