Official SDKv1.x

Python SDK

Official Python SDK for SnapSharp. Screenshots, OG images, site audit. pip install snapsharp

Installation

Install the Python SDK using your package manager:

shell

pip install snapsharp

Then import and initialise the client:

python

from snapsharp import SnapSharp

snap = SnapSharp("sk_live_...")

Replace sk_live_... with your API key from the dashboard.

Quick Start

Three common use cases to get you up and running in minutes.

1. Take a Screenshot

Capture a viewport or full-page screenshot and write it to a file.

python

from snapsharp import SnapSharp

snap = SnapSharp("sk_live_...")

image = snap.screenshot(
    "https://example.com",
    width=1280,
    height=720,
    format="png",
    full_page=False,
)

with open("screenshot.png", "wb") as f:
    f.write(image)

print("Screenshot saved!")

2. Generate an OG Image

Create social-media-ready Open Graph images from any URL.

python

from snapsharp import SnapSharp

snap = SnapSharp("sk_live_...")

og = snap.og_image(
    "https://example.com",
    template="default",
    width=1200,
    height=630,
)

with open("og-image.png", "wb") as f:
    f.write(og)

3. Render HTML to Image

Convert raw HTML and CSS into a high-quality image.

python

from snapsharp import SnapSharp

snap = SnapSharp("sk_live_...")

image = snap.html_to_image(
    "<h1>Hello World</h1><p>Rendered with SnapSharp</p>",
    width=800,
    height=400,
    format="png",
    css="body { font-family: sans-serif; background: #1a1a2e; color: #fff; display: grid; place-items: center; }",
)

with open("html-render.png", "wb") as f:
    f.write(image)

API Reference

Complete list of methods available on the Python client.

screenshot()

screenshot(url: str, **kwargs) -> bytes

Captures a screenshot of the given URL. Accepts width, height, format, full_page, device, dark_mode, delay, and headers keyword arguments.

og_image()

og_image(url: str, **kwargs) -> bytes

Generates an Open Graph image for the URL using built-in or custom templates. Returns image bytes.

html_to_image()

html_to_image(html: str, **kwargs) -> bytes

Renders raw HTML/CSS to an image. Supports inline styles, custom viewport size, and transparent backgrounds.

site_audit()

site_audit(url: str, **kwargs) -> dict

Runs a Lighthouse-style audit. Returns a dict with performance, accessibility, SEO, and best practices scores.

All methods that return images accept an optional format parameter ("png", "jpeg", "webp"). Default is "png". See the full API reference for every available option.

Error Handling

The SDK throws typed errors with HTTP status, message, and a unique request ID for debugging. Always wrap calls in a try/catch to handle rate limits and authentication errors gracefully.

python

from snapsharp import SnapSharp, SnapSharpError

snap = SnapSharp("sk_live_...")

try:
    image = snap.screenshot("https://example.com")
except SnapSharpError as e:
    print(f"Error {e.status}: {e.message}")
    print(f"Request ID: {e.request_id}")

    if e.status == 401:
        print("Invalid API key. Check your credentials.")
    if e.status == 429:
        print(f"Rate limited. Retry after {e.retry_after}s")

Status	Meaning	Action
400	Bad Request — invalid parameters	Check the request body and query params
401	Unauthorized — invalid or missing API key	Verify your API key in the dashboard
429	Too Many Requests — rate limit exceeded	Wait for `retryAfter` seconds
500	Internal Server Error	Retry with exponential back-off

Configuration

Customise the client with optional settings passed at initialisation.

python

snap = SnapSharp(
    "sk_live_...",
    base_url="https://api.snapsharp.dev",  # Custom API base URL
    timeout=30,                             # Request timeout in seconds
    retries=2,                              # Auto-retry on 5xx errors
)

Option	Default	Description
baseUrl	api.snapsharp.dev	Override the API base URL (e.g. for on-premise)
timeout	30s	Maximum time to wait for a response
retries	0	Number of automatic retries on 5xx errors

SDKs for other languages

Node.js PHP Go Ruby

Ready to start building?

Get your free API key and start capturing screenshots in under a minute. 100 free screenshots every month — no credit card required.

Get Free API Key Read the Docs