# rendshot

Official Python SDK for [RendShot](https://rendshot.ai) — HTML-to-image rendering and URL screenshots.

## Installation

```bash
pip install rendshot
```

## Quick Start

```python
from rendshot import RendshotClient, RenderImageOptions, ScreenshotUrlOptions

client = RendshotClient(api_key="rs_live_...")

# Render HTML to image
result = client.render_image(RenderImageOptions(
    html="<h1 style='color: green;'>Hello World</h1>",
    width=800,
    height=400,
))
print(result.url)

# Screenshot a URL
result = client.screenshot_url(ScreenshotUrlOptions(url="https://example.com"))
print(result.url)
```

## Async

```python
from rendshot import AsyncRendshotClient, ScreenshotUrlOptions

async with AsyncRendshotClient(api_key="rs_live_...") as client:
    result = await client.screenshot_url(
        ScreenshotUrlOptions(url="https://example.com", full_page=True)
    )
    print(result.url)
```

## API

### `RendshotClient` / `AsyncRendshotClient`

```python
client = RendshotClient(api_key="rs_live_...", base_url="https://api.rendshot.ai")
```

Both clients support context managers and expose the same methods:

| Method | Description |
|--------|-------------|
| `render_image(options)` | Render HTML/CSS to an image |
| `screenshot_url(options)` | Take a screenshot of a URL |
| `get_usage()` | Get current month's usage |
| `get_image(image_id)` | Get metadata for a specific image |

### Options

All option classes accept keyword arguments and convert Python `snake_case` to API `camelCase` automatically.

**`RenderImageOptions`**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `html` | `str` | required | HTML content to render |
| `css` | `str` | — | Optional CSS styles |
| `width` | `int` | 1080 | Image width (1–4096) |
| `height` | `int` | 1080 | Image height (1–4096) |
| `format` | `"png" \| "jpg"` | `"png"` | Output format |
| `quality` | `int` | 90 | JPEG quality (1–100) |
| `device_scale` | `1 \| 2 \| 3` | 1 | Device scale factor |
| `fonts` | `list[str]` | — | Custom fonts |
| `timeout` | `int` | 10000 | Timeout in ms (1000–30000) |

**`ScreenshotUrlOptions`**

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `url` | `str` | required | URL to screenshot |
| `width` | `int` | 1280 | Viewport width (1–4096) |
| `height` | `int` | 800 | Viewport height (1–4096) |
| `format` | `"png" \| "jpg"` | `"png"` | Output format |
| `quality` | `int` | 90 | JPEG quality (1–100) |
| `full_page` | `bool` | `False` | Capture full page |
| `device_scale` | `1 \| 2 \| 3` | 1 | Device scale factor |
| `timeout` | `int` | 10000 | Timeout in ms (1000–30000) |

### Error Handling

```python
from rendshot import RendshotClient, RendshotError, RenderImageOptions

client = RendshotClient(api_key="rs_live_...")

try:
    client.render_image(RenderImageOptions(html="<h1>Hello</h1>"))
except RendshotError as e:
    print(e.code)     # "RATE_LIMIT_EXCEEDED"
    print(e.status)   # 429
    print(e)          # "Rate limited"
```

## License

MIT
