shotapi 1.0.0

Python SDK for ShotAPI - Screenshot & Rendering API

ShotAPI Python SDK

Official Python SDK for ShotAPI - The Screenshot & Rendering API.

Installation

pip install shotapi

Quick Start

from shotapi import ShotAPI

# Initialize the client
client = ShotAPI("sk_your_api_key")

# Take a screenshot
image = client.screenshot("https://example.com")
with open("screenshot.png", "wb") as f:
    f.write(image)

Features

• URL Screenshots - Capture any webpage as PNG, JPEG, WebP, or PDF
• HTML Rendering - Convert HTML/CSS to images
• Metadata Extraction - Get OG tags, title, description, tech stack
• Batch Processing - Screenshot multiple URLs in parallel
• Visual Diff - Compare two pages and get difference percentage

Usage Examples

Basic Screenshot

from shotapi import ShotAPI

client = ShotAPI("sk_your_api_key")

# Simple screenshot
image = client.screenshot("https://stripe.com")

# Full-page screenshot
image = client.screenshot(
    "https://github.com",
    full_page=True,
    format="png"
)

# With options
image = client.screenshot(
    "https://example.com",
    width=1920,
    height=1080,
    dark_mode=True,
    device_scale_factor=2,
    block_ads=True,
)

Device Mockups

# Wrap in iPhone frame
image = client.screenshot(
    "https://example.com",
    mockup="iphone"
)

# MacBook mockup
image = client.screenshot(
    "https://example.com",
    mockup="macbook"
)

HTML to Image

# Render HTML to image
html = """
<div style="padding: 40px; background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);">
    <h1 style="color: white; font-family: sans-serif;">Hello World!</h1>
</div>
"""

image = client.render(html, width=800, height=400)

Metadata Extraction

# Get page metadata
meta = client.metadata("https://github.com")
print(meta["title"])
print(meta["description"])
print(meta["og_image"])

# With markdown content
meta = client.metadata("https://example.com", extract_markdown=True)
print(meta["markdown"])

Batch Screenshots

# Capture multiple URLs
urls = [
    "https://google.com",
    "https://github.com",
    "https://stripe.com",
]

result = client.batch(urls, format="png", full_page=True)
for item in result["results"]:
    print(f"{item['url']} -> {item['filename']}")

Visual Diff

# Compare two pages
diff_image, diff_percentage = client.diff(
    "https://example.com",
    "https://example.org"
)

print(f"Pages differ by {diff_percentage}%")
with open("diff.png", "wb") as f:
    f.write(diff_image)

Advanced Options

# Full control over the capture
image = client.screenshot(
    "https://example.com",
    width=1280,
    height=720,
    full_page=True,
    format="png",
    delay=2,  # Wait 2 seconds before capture
    dark_mode=True,
    device_scale_factor=2,
    custom_css="body { font-family: 'Comic Sans MS' !important; }",
    custom_js="document.querySelector('.popup').remove()",
    wait_for_selector=".content-loaded",
    click_selector=".accept-cookies",
    hide_selectors=[".ad-banner", ".newsletter-popup"],
    block_ads=True,
    headers={"Authorization": "Bearer token"},
    cookies=[{"name": "session", "value": "abc123", "domain": "example.com"}],
    geolocation={"latitude": 40.7128, "longitude": -74.0060},
    timezone="America/New_York",
)

Error Handling

from shotapi import ShotAPI, ShotAPIError, AuthenticationError, RateLimitError

client = ShotAPI("sk_your_api_key")

try:
    image = client.screenshot("https://example.com")
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")
except ShotAPIError as e:
    print(f"API error: {e.message}")

Context Manager

# Automatically close connection
with ShotAPI("sk_your_api_key") as client:
    image = client.screenshot("https://example.com")

Configuration

# Custom base URL and timeout
client = ShotAPI(
    api_key="sk_your_api_key",
    base_url="https://shotapi.net",  # default
    timeout=120.0,  # seconds
)

Pro/Max Features

Some features require a Pro or Max plan:

Feature	Free	Pro	Max
Basic screenshots	Yes	Yes	Yes
Full-page capture	Yes	Yes	Yes
Dark mode	No	Yes	Yes
Device mockups	No	Yes	Yes
Custom CSS/JS	No	Yes	Yes
Element selection	No	Yes	Yes
Geo/Timezone emulation	No	Yes	Yes
Block ads	No	Yes	Yes
Batch processing	No	Yes	Yes
Markdown extraction	No	Yes	Yes

Links

• Documentation
• Pricing
• Dashboard

License

MIT License - see LICENSE file for details.