shotapi 1.0.0
Python SDK for ShotAPI - Screenshot & Rendering API
License: MIT
Requires Python: >=3.8
Keywords: screenshot, api, web, capture, render, html, image, pdf

# ShotAPI Python SDK

Official Python SDK for [ShotAPI](https://shotapi.net) - The Screenshot & Rendering API.

## Installation

```bash
pip install shotapi
```

## Quick Start

```python
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

```python
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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
# 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

```python
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

```python
# Automatically close connection
with ShotAPI("sk_your_api_key") as client:
    image = client.screenshot("https://example.com")
```

## Configuration

```python
# 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](https://shotapi.net/docs-page)
- [Pricing](https://shotapi.net/pricing)
- [Dashboard](https://shotapi.net/dashboard)

## License

MIT License - see LICENSE file for details.