rendshot 0.1.0__tar.gz

rendshot-0.1.0/.gitignore

@@ -0,0 +1,10 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.tgz
+.turbo/
+.vercel
+bun.lock
+bun.lockb

rendshot-0.1.0/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: rendshot
+Version: 0.1.0
+Summary: Official Python SDK for RendShot — HTML-to-image rendering and URL screenshots
+Project-URL: Homepage, https://rendshot.ai
+Project-URL: Documentation, https://rendshot.ai/docs/sdk
+Project-URL: Repository, https://github.com/nicepkg/rendshot
+Author-email: RendShot <support@rendshot.ai>
+License-Expression: MIT
+Keywords: api,html-to-image,rendering,rendshot,screenshot,sdk
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: respx>=0.22; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# 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

rendshot-0.1.0/README.md

@@ -0,0 +1,108 @@
+# 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

rendshot-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "rendshot"
+version = "0.1.0"
+description = "Official Python SDK for RendShot — HTML-to-image rendering and URL screenshots"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [{ name = "RendShot", email = "support@rendshot.ai" }]
+keywords = ["rendshot", "screenshot", "html-to-image", "rendering", "sdk", "api"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://rendshot.ai"
+Documentation = "https://rendshot.ai/docs/sdk"
+Repository = "https://github.com/nicepkg/rendshot"
+
+[project.optional-dependencies]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "respx>=0.22"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["rendshot"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"

rendshot-0.1.0/rendshot/__init__.py

@@ -0,0 +1,24 @@
+"""Official Python SDK for RendShot — HTML-to-image rendering and URL screenshots."""
+
+from rendshot.client import RendshotClient, AsyncRendshotClient
+from rendshot.errors import RendshotError
+from rendshot.types import (
+    RenderImageOptions,
+    ScreenshotUrlOptions,
+    ImageResult,
+    ImageMetadata,
+    UsageResult,
+)
+from rendshot._version import __version__
+
+__all__ = [
+    "RendshotClient",
+    "AsyncRendshotClient",
+    "RendshotError",
+    "RenderImageOptions",
+    "ScreenshotUrlOptions",
+    "ImageResult",
+    "ImageMetadata",
+    "UsageResult",
+    "__version__",
+]

rendshot-0.1.0/rendshot/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

rendshot-0.1.0/rendshot/client.py

@@ -0,0 +1,166 @@
+"""Sync and async HTTP clients for the RendShot API."""
+
+from __future__ import annotations
+
+from typing import Any
+from urllib.parse import quote
+
+import httpx
+
+from rendshot._version import __version__
+from rendshot.errors import RendshotError
+from rendshot.types import (
+    ImageMetadata,
+    ImageResult,
+    RenderImageOptions,
+    ScreenshotUrlOptions,
+    UsageResult,
+)
+
+_DEFAULT_BASE_URL = "https://api.rendshot.ai"
+_TIMEOUT = httpx.Timeout(60.0, connect=10.0)
+
+
+def _base_headers(api_key: str) -> dict[str, str]:
+    return {
+        "Authorization": f"Bearer {api_key}",
+        "User-Agent": f"rendshot-python/{__version__}",
+    }
+
+
+def _handle_response(response: httpx.Response) -> Any:
+    try:
+        data = response.json()
+    except (ValueError, httpx.DecodingError):
+        if not response.is_success:
+            raise RendshotError("UNKNOWN_ERROR", f"API error: {response.status_code}", response.status_code)
+        raise ValueError(f"Unexpected non-JSON response (status {response.status_code})")
+
+    if not response.is_success:
+        err = data.get("error", {}) if isinstance(data, dict) else {}
+        raise RendshotError(
+            code=err.get("code", "UNKNOWN_ERROR"),
+            message=err.get("message", f"API error: {response.status_code}"),
+            status=err.get("status", response.status_code),
+        )
+    return data
+
+
+class RendshotClient:
+    """Synchronous RendShot API client.
+
+    Usage::
+
+        from rendshot import RendshotClient, RenderImageOptions
+
+        client = RendshotClient(api_key="rs_live_...")
+        result = client.render_image(RenderImageOptions(html="<h1>Hello</h1>"))
+        print(result.url)
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = _DEFAULT_BASE_URL) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.Client(
+            headers=_base_headers(api_key),
+            timeout=_TIMEOUT,
+        )
+
+    def render_image(self, options: RenderImageOptions | dict) -> ImageResult:
+        """Render HTML/CSS to an image."""
+        body = options.to_dict() if isinstance(options, RenderImageOptions) else options
+        data = self._post("/v1/image", body)
+        return ImageResult.from_dict(data)
+
+    def screenshot_url(self, options: ScreenshotUrlOptions | dict) -> ImageResult:
+        """Take a screenshot of a URL."""
+        body = options.to_dict() if isinstance(options, ScreenshotUrlOptions) else options
+        data = self._post("/v1/screenshot", body)
+        return ImageResult.from_dict(data)
+
+    def get_usage(self) -> UsageResult:
+        """Get current month's usage."""
+        data = self._get("/v1/usage")
+        return UsageResult.from_dict(data)
+
+    def get_image(self, image_id: str) -> ImageMetadata:
+        """Get metadata for a specific image."""
+        data = self._get(f"/v1/image/{quote(image_id, safe='')}")
+        return ImageMetadata.from_dict(data)
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._client.close()
+
+    def __enter__(self) -> "RendshotClient":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def _post(self, path: str, body: dict) -> Any:
+        resp = self._client.post(f"{self._base_url}{path}", json=body)
+        return _handle_response(resp)
+
+    def _get(self, path: str) -> Any:
+        resp = self._client.get(f"{self._base_url}{path}")
+        return _handle_response(resp)
+
+
+class AsyncRendshotClient:
+    """Async RendShot API client.
+
+    Usage::
+
+        from rendshot import AsyncRendshotClient, RenderImageOptions
+
+        async with AsyncRendshotClient(api_key="rs_live_...") as client:
+            result = await client.render_image(RenderImageOptions(html="<h1>Hello</h1>"))
+            print(result.url)
+    """
+
+    def __init__(self, api_key: str, *, base_url: str = _DEFAULT_BASE_URL) -> None:
+        self._base_url = base_url.rstrip("/")
+        self._client = httpx.AsyncClient(
+            headers=_base_headers(api_key),
+            timeout=_TIMEOUT,
+        )
+
+    async def render_image(self, options: RenderImageOptions | dict) -> ImageResult:
+        """Render HTML/CSS to an image."""
+        body = options.to_dict() if isinstance(options, RenderImageOptions) else options
+        data = await self._post("/v1/image", body)
+        return ImageResult.from_dict(data)
+
+    async def screenshot_url(self, options: ScreenshotUrlOptions | dict) -> ImageResult:
+        """Take a screenshot of a URL."""
+        body = options.to_dict() if isinstance(options, ScreenshotUrlOptions) else options
+        data = await self._post("/v1/screenshot", body)
+        return ImageResult.from_dict(data)
+
+    async def get_usage(self) -> UsageResult:
+        """Get current month's usage."""
+        data = await self._get("/v1/usage")
+        return UsageResult.from_dict(data)
+
+    async def get_image(self, image_id: str) -> ImageMetadata:
+        """Get metadata for a specific image."""
+        data = await self._get(f"/v1/image/{quote(image_id, safe='')}")
+        return ImageMetadata.from_dict(data)
+
+    async def close(self) -> None:
+        """Close the underlying HTTP client."""
+        await self._client.aclose()
+
+    async def __aenter__(self) -> "AsyncRendshotClient":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    async def _post(self, path: str, body: dict) -> Any:
+        resp = await self._client.post(f"{self._base_url}{path}", json=body)
+        return _handle_response(resp)
+
+    async def _get(self, path: str) -> Any:
+        resp = await self._client.get(f"{self._base_url}{path}")
+        return _handle_response(resp)

rendshot-0.1.0/rendshot/errors.py

@@ -0,0 +1,16 @@
+"""Error types for the RendShot SDK."""
+
+from __future__ import annotations
+
+
+class RendshotError(Exception):
+    """Error returned by the RendShot API."""
+
+    def __init__(self, code: str, message: str, status: int) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.status = status
+
+    def __repr__(self) -> str:
+        return f"RendshotError(code={self.code!r}, status={self.status}, message={self.message!r})"

rendshot-0.1.0/rendshot/types.py

@@ -0,0 +1,137 @@
+"""Type definitions for the RendShot SDK."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+
+@dataclass
+class RenderImageOptions:
+    """Options for rendering HTML to an image."""
+
+    html: str
+    css: str | None = None
+    width: int | None = None
+    height: int | None = None
+    format: Literal["png", "jpg"] | None = None
+    quality: int | None = None
+    device_scale: Literal[1, 2, 3] | None = None
+    fonts: list[str] | None = None
+    timeout: int | None = None
+
+    def to_dict(self) -> dict:
+        d: dict = {"html": self.html}
+        if self.css is not None:
+            d["css"] = self.css
+        if self.width is not None:
+            d["width"] = self.width
+        if self.height is not None:
+            d["height"] = self.height
+        if self.format is not None:
+            d["format"] = self.format
+        if self.quality is not None:
+            d["quality"] = self.quality
+        if self.device_scale is not None:
+            d["deviceScale"] = self.device_scale
+        if self.fonts is not None:
+            d["fonts"] = self.fonts
+        if self.timeout is not None:
+            d["timeout"] = self.timeout
+        return d
+
+
+@dataclass
+class ScreenshotUrlOptions:
+    """Options for taking a URL screenshot."""
+
+    url: str
+    width: int | None = None
+    height: int | None = None
+    format: Literal["png", "jpg"] | None = None
+    quality: int | None = None
+    full_page: bool | None = None
+    device_scale: Literal[1, 2, 3] | None = None
+    timeout: int | None = None
+
+    def to_dict(self) -> dict:
+        d: dict = {"url": self.url}
+        if self.width is not None:
+            d["width"] = self.width
+        if self.height is not None:
+            d["height"] = self.height
+        if self.format is not None:
+            d["format"] = self.format
+        if self.quality is not None:
+            d["quality"] = self.quality
+        if self.full_page is not None:
+            d["fullPage"] = self.full_page
+        if self.device_scale is not None:
+            d["deviceScale"] = self.device_scale
+        if self.timeout is not None:
+            d["timeout"] = self.timeout
+        return d
+
+
+@dataclass
+class ImageResult:
+    """Result from a render or screenshot operation."""
+
+    image_id: str
+    url: str
+    width: int
+    height: int
+    format: str
+    size: int
+    created_at: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ImageResult":
+        return cls(
+            image_id=data["imageId"],
+            url=data["url"],
+            width=data["width"],
+            height=data["height"],
+            format=data["format"],
+            size=data["size"],
+            created_at=data["createdAt"],
+        )
+
+
+@dataclass
+class ImageMetadata(ImageResult):
+    """Image metadata including expiration."""
+
+    expires_at: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "ImageMetadata":
+        return cls(
+            image_id=data["imageId"],
+            url=data["url"],
+            width=data["width"],
+            height=data["height"],
+            format=data["format"],
+            size=data["size"],
+            created_at=data["createdAt"],
+            expires_at=data.get("expiresAt"),
+        )
+
+
+@dataclass
+class UsageResult:
+    """Current usage information."""
+
+    month: str
+    count: int
+    limit: int
+    plan: str
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "UsageResult":
+        return cls(
+            month=data["month"],
+            count=data["count"],
+            limit=data["limit"],
+            plan=data["plan"],
+        )

rendshot-0.1.0/tests/test_client.py

@@ -0,0 +1,454 @@
+"""Tests for the RendShot Python SDK."""
+
+from __future__ import annotations
+
+import pytest
+import httpx
+import respx
+
+from rendshot import (
+    RendshotClient,
+    AsyncRendshotClient,
+    RendshotError,
+    RenderImageOptions,
+    ScreenshotUrlOptions,
+    ImageResult,
+    ImageMetadata,
+    UsageResult,
+)
+
+BASE = "https://api.rendshot.ai"
+
+IMAGE_RESP = {
+    "imageId": "img_1",
+    "url": "https://cdn/img.png",
+    "width": 800,
+    "height": 600,
+    "format": "png",
+    "size": 1234,
+    "createdAt": "2026-03-20",
+}
+
+USAGE_RESP = {"month": "2026-03", "count": 42, "limit": 1000, "plan": "pro"}
+
+META_RESP = {**IMAGE_RESP, "imageId": "img_3", "expiresAt": "2026-03-27"}
+
+
+# ---------------------------------------------------------------------------
+# Constructor
+# ---------------------------------------------------------------------------
+
+
+class TestConstructor:
+    @respx.mock
+    def test_default_base_url(self):
+        route = respx.get(f"{BASE}/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        client.get_usage()
+        assert route.called
+
+    @respx.mock
+    def test_strips_trailing_slash(self):
+        route = respx.get("https://custom.api.com/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test", base_url="https://custom.api.com/")
+        client.get_usage()
+        assert route.called
+
+    @respx.mock
+    def test_context_manager(self):
+        respx.get(f"{BASE}/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        with RendshotClient(api_key="rs_live_test") as client:
+            result = client.get_usage()
+        assert result.plan == "pro"
+
+
+# ---------------------------------------------------------------------------
+# Headers
+# ---------------------------------------------------------------------------
+
+
+class TestHeaders:
+    @respx.mock
+    def test_sends_auth_and_user_agent_on_post(self):
+        route = respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_abc")
+        client.render_image(RenderImageOptions(html="<h1>hi</h1>"))
+
+        req = route.calls[0].request
+        assert req.headers["authorization"] == "Bearer rs_live_abc"
+        assert "rendshot-python/" in req.headers["user-agent"]
+
+    @respx.mock
+    def test_sends_auth_and_user_agent_on_get(self):
+        route = respx.get(f"{BASE}/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_abc")
+        client.get_usage()
+
+        req = route.calls[0].request
+        assert req.headers["authorization"] == "Bearer rs_live_abc"
+        assert "rendshot-python/" in req.headers["user-agent"]
+
+
+# ---------------------------------------------------------------------------
+# render_image
+# ---------------------------------------------------------------------------
+
+
+class TestRenderImage:
+    @respx.mock
+    def test_posts_to_v1_image(self):
+        route = respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        result = client.render_image(
+            RenderImageOptions(html="<h1>Hello</h1>", width=800, height=600, format="png")
+        )
+
+        assert route.called
+        import json
+        body = json.loads(route.calls[0].request.content)
+        assert body["html"] == "<h1>Hello</h1>"
+        assert body["width"] == 800
+        assert isinstance(result, ImageResult)
+        assert result.image_id == "img_1"
+        assert result.url == "https://cdn/img.png"
+
+    @respx.mock
+    def test_accepts_dict(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        result = client.render_image({"html": "<h1>Hello</h1>"})
+        assert result.image_id == "img_1"
+
+    @respx.mock
+    def test_fonts_and_timeout_reach_wire(self):
+        route = respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        client.render_image(RenderImageOptions(html="<h1>x</h1>", fonts=["Inter", "Roboto"], timeout=5000))
+
+        import json
+        body = json.loads(route.calls[0].request.content)
+        assert body["fonts"] == ["Inter", "Roboto"]
+        assert body["timeout"] == 5000
+
+    @respx.mock
+    def test_device_scale_maps_to_camel_case(self):
+        route = respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        client.render_image(RenderImageOptions(html="<h1>x</h1>", device_scale=2))
+
+        import json
+        body = json.loads(route.calls[0].request.content)
+        assert body["deviceScale"] == 2
+        assert "device_scale" not in body
+
+
+# ---------------------------------------------------------------------------
+# screenshot_url
+# ---------------------------------------------------------------------------
+
+
+class TestScreenshotUrl:
+    @respx.mock
+    def test_posts_to_v1_screenshot(self):
+        shot_resp = {**IMAGE_RESP, "imageId": "img_2", "width": 1280, "height": 800}
+        route = respx.post(f"{BASE}/v1/screenshot").mock(
+            return_value=httpx.Response(200, json=shot_resp)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        result = client.screenshot_url(
+            ScreenshotUrlOptions(url="https://example.com", full_page=True)
+        )
+
+        import json
+        body = json.loads(route.calls[0].request.content)
+        assert body["url"] == "https://example.com"
+        assert body["fullPage"] is True
+        assert result.image_id == "img_2"
+
+    @respx.mock
+    def test_accepts_dict(self):
+        respx.post(f"{BASE}/v1/screenshot").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        result = client.screenshot_url({"url": "https://example.com"})
+        assert result.image_id == "img_1"
+
+    @respx.mock
+    def test_device_scale_maps_to_camel_case(self):
+        route = respx.post(f"{BASE}/v1/screenshot").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        client.screenshot_url(ScreenshotUrlOptions(url="https://example.com", device_scale=2))
+
+        import json
+        body = json.loads(route.calls[0].request.content)
+        assert body["deviceScale"] == 2
+        assert "device_scale" not in body
+
+
+# ---------------------------------------------------------------------------
+# get_usage
+# ---------------------------------------------------------------------------
+
+
+class TestGetUsage:
+    @respx.mock
+    def test_returns_typed_result(self):
+        respx.get(f"{BASE}/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        result = client.get_usage()
+
+        assert isinstance(result, UsageResult)
+        assert result.plan == "pro"
+        assert result.count == 42
+        assert result.limit == 1000
+
+
+# ---------------------------------------------------------------------------
+# get_image
+# ---------------------------------------------------------------------------
+
+
+class TestGetImage:
+    @respx.mock
+    def test_returns_metadata(self):
+        respx.get(f"{BASE}/v1/image/img_3").mock(
+            return_value=httpx.Response(200, json=META_RESP)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        result = client.get_image("img_3")
+
+        assert isinstance(result, ImageMetadata)
+        assert result.expires_at == "2026-03-27"
+
+    @respx.mock
+    def test_encodes_image_id(self):
+        encoded_resp = {**META_RESP, "imageId": "img/special"}
+        route = respx.get(f"{BASE}/v1/image/img%2Fspecial").mock(
+            return_value=httpx.Response(200, json=encoded_resp)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        client.get_image("img/special")
+        assert route.called
+
+
+# ---------------------------------------------------------------------------
+# Error handling
+# ---------------------------------------------------------------------------
+
+
+class TestErrors:
+    @respx.mock
+    def test_api_error_with_code_and_status(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(
+                429,
+                json={"error": {"code": "RATE_LIMIT_EXCEEDED", "message": "Rate limited", "status": 429}},
+            )
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        with pytest.raises(RendshotError) as exc_info:
+            client.render_image(RenderImageOptions(html="<p>x</p>"))
+
+        assert exc_info.value.code == "RATE_LIMIT_EXCEEDED"
+        assert exc_info.value.status == 429
+        assert exc_info.value.message == "Rate limited"
+        assert "Rate limited" in str(exc_info.value)
+
+    @respx.mock
+    def test_fallback_when_no_error_field(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(500, json={})
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        with pytest.raises(RendshotError) as exc_info:
+            client.render_image(RenderImageOptions(html="<p>x</p>"))
+
+        assert exc_info.value.code == "UNKNOWN_ERROR"
+        assert exc_info.value.status == 500
+
+    @respx.mock
+    def test_non_json_error_response(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(502, text="Bad Gateway")
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        with pytest.raises(RendshotError) as exc_info:
+            client.render_image(RenderImageOptions(html="<p>x</p>"))
+
+        assert exc_info.value.code == "UNKNOWN_ERROR"
+        assert exc_info.value.status == 502
+
+    @respx.mock
+    def test_non_dict_json_error_body(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(500, json=None)
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        with pytest.raises(RendshotError) as exc_info:
+            client.render_image(RenderImageOptions(html="<p>x</p>"))
+        assert exc_info.value.code == "UNKNOWN_ERROR"
+        assert exc_info.value.status == 500
+
+    @respx.mock
+    def test_non_json_ok_response(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, text="OK")
+        )
+        client = RendshotClient(api_key="rs_live_test")
+        with pytest.raises(ValueError, match="non-JSON"):
+            client.render_image(RenderImageOptions(html="<p>x</p>"))
+
+
+# ---------------------------------------------------------------------------
+# Async client
+# ---------------------------------------------------------------------------
+
+
+class TestAsyncClient:
+    @respx.mock
+    async def test_render_image(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        async with AsyncRendshotClient(api_key="rs_live_test") as client:
+            result = await client.render_image(RenderImageOptions(html="<h1>hi</h1>"))
+        assert result.image_id == "img_1"
+
+    @respx.mock
+    async def test_screenshot_url(self):
+        respx.post(f"{BASE}/v1/screenshot").mock(
+            return_value=httpx.Response(200, json=IMAGE_RESP)
+        )
+        async with AsyncRendshotClient(api_key="rs_live_test") as client:
+            result = await client.screenshot_url(ScreenshotUrlOptions(url="https://example.com"))
+        assert result.image_id == "img_1"
+
+    @respx.mock
+    async def test_get_usage(self):
+        respx.get(f"{BASE}/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        async with AsyncRendshotClient(api_key="rs_live_test") as client:
+            result = await client.get_usage()
+        assert result.plan == "pro"
+
+    @respx.mock
+    async def test_get_image(self):
+        respx.get(f"{BASE}/v1/image/img_3").mock(
+            return_value=httpx.Response(200, json=META_RESP)
+        )
+        async with AsyncRendshotClient(api_key="rs_live_test") as client:
+            result = await client.get_image("img_3")
+        assert result.expires_at == "2026-03-27"
+
+    @respx.mock
+    async def test_error_handling(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(
+                401,
+                json={"error": {"code": "UNAUTHORIZED", "message": "Invalid API key", "status": 401}},
+            )
+        )
+        async with AsyncRendshotClient(api_key="bad_key") as client:
+            with pytest.raises(RendshotError) as exc_info:
+                await client.render_image(RenderImageOptions(html="<p>x</p>"))
+        assert exc_info.value.code == "UNAUTHORIZED"
+
+    @respx.mock
+    async def test_non_json_error_response(self):
+        respx.post(f"{BASE}/v1/image").mock(
+            return_value=httpx.Response(502, text="Bad Gateway")
+        )
+        async with AsyncRendshotClient(api_key="rs_live_test") as client:
+            with pytest.raises(RendshotError) as exc_info:
+                await client.render_image(RenderImageOptions(html="<p>x</p>"))
+        assert exc_info.value.code == "UNKNOWN_ERROR"
+        assert exc_info.value.status == 502
+
+    @respx.mock
+    async def test_custom_base_url(self):
+        route = respx.get("https://custom.api.com/v1/usage").mock(
+            return_value=httpx.Response(200, json=USAGE_RESP)
+        )
+        async with AsyncRendshotClient(api_key="rs_live_test", base_url="https://custom.api.com/") as client:
+            await client.get_usage()
+        assert route.called
+
+
+# ---------------------------------------------------------------------------
+# Types
+# ---------------------------------------------------------------------------
+
+
+class TestTypes:
+    def test_render_options_to_dict_minimal(self):
+        opts = RenderImageOptions(html="<h1>hi</h1>")
+        d = opts.to_dict()
+        assert d == {"html": "<h1>hi</h1>"}
+
+    def test_render_options_to_dict_full(self):
+        opts = RenderImageOptions(
+            html="<h1>hi</h1>",
+            css="h1 { color: red; }",
+            width=800,
+            height=600,
+            format="jpg",
+            quality=85,
+            device_scale=2,
+            fonts=["Inter"],
+            timeout=5000,
+        )
+        d = opts.to_dict()
+        assert d["css"] == "h1 { color: red; }"
+        assert d["deviceScale"] == 2
+        assert d["fonts"] == ["Inter"]
+        assert "device_scale" not in d
+
+    def test_screenshot_options_to_dict(self):
+        opts = ScreenshotUrlOptions(
+            url="https://example.com",
+            full_page=True,
+            device_scale=3,
+        )
+        d = opts.to_dict()
+        assert d["fullPage"] is True
+        assert d["deviceScale"] == 3
+        assert "full_page" not in d
+
+    def test_image_result_from_dict(self):
+        result = ImageResult.from_dict(IMAGE_RESP)
+        assert result.image_id == "img_1"
+        assert result.created_at == "2026-03-20"
+
+    def test_image_metadata_from_dict(self):
+        meta = ImageMetadata.from_dict(META_RESP)
+        assert meta.expires_at == "2026-03-27"
+        assert meta.image_id == "img_3"
+
+    def test_usage_result_from_dict(self):
+        usage = UsageResult.from_dict(USAGE_RESP)
+        assert usage.month == "2026-03"
+        assert usage.count == 42