screenshotapi-to 1.0.0__py3-none-any.whl

screenshotapi/__init__.py

@@ -0,0 +1,38 @@
+from .client import ScreenshotAPI
+from .errors import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidAPIKeyError,
+    NetworkError,
+    ScreenshotAPIError,
+    ScreenshotFailedError,
+)
+from .types import (
+    ColorScheme,
+    MockupDevice,
+    ScreenshotFormat,
+    ScreenshotMetadata,
+    ScreenshotOptions,
+    ScreenshotResult,
+    WaitUntil,
+)
+
+__version__ = "1.0.0"
+
+__all__ = [
+    "__version__",
+    "ScreenshotAPI",
+    "ScreenshotAPIError",
+    "AuthenticationError",
+    "InsufficientCreditsError",
+    "InvalidAPIKeyError",
+    "ScreenshotFailedError",
+    "NetworkError",
+    "ScreenshotOptions",
+    "ScreenshotMetadata",
+    "ScreenshotResult",
+    "ScreenshotFormat",
+    "ColorScheme",
+    "WaitUntil",
+    "MockupDevice",
+]

screenshotapi/client.py

@@ -0,0 +1,326 @@
+from __future__ import annotations
+
+from collections.abc import Mapping as MappingABC
+from collections.abc import Sequence as SequenceABC
+from pathlib import Path
+from typing import Dict, Mapping, NoReturn, Optional, Sequence, Union
+
+import httpx
+
+from .errors import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidAPIKeyError,
+    NetworkError,
+    ScreenshotAPIError,
+    ScreenshotFailedError,
+)
+from .types import ScreenshotMetadata, ScreenshotOptions, ScreenshotResult
+
+DEFAULT_BASE_URL = "https://screenshotapi.to"
+DEFAULT_TIMEOUT = 60.0
+
+ScreenshotOptionsInput = Union[ScreenshotOptions, Mapping[str, object]]
+
+
+class ScreenshotAPI:
+    """Client for the ScreenshotAPI service."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        base_url: str = DEFAULT_BASE_URL,
+        timeout: float = DEFAULT_TIMEOUT,
+        transport: Optional[httpx.BaseTransport] = None,
+        async_transport: Optional[httpx.AsyncBaseTransport] = None,
+    ) -> None:
+        if not api_key:
+            raise ValueError("API key is required")
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._transport = transport
+        self._async_transport = async_transport
+
+    def _coerce_options(self, options: ScreenshotOptionsInput) -> ScreenshotOptions:
+        if isinstance(options, ScreenshotOptions):
+            return options
+
+        if not isinstance(options, MappingABC):
+            raise TypeError("options must be a ScreenshotOptions instance or mapping")
+
+        try:
+            return ScreenshotOptions(**dict(options))  # type: ignore[arg-type]
+        except TypeError as exc:
+            raise ValueError(f"Invalid screenshot options: {exc}") from exc
+
+    def _validate_options(self, options: ScreenshotOptions) -> None:
+        if not options.url and not options.html:
+            raise ValueError("Either url or html is required")
+
+        if (options.geo_latitude is None) != (options.geo_longitude is None):
+            raise ValueError("geo_latitude and geo_longitude must be provided together")
+
+    def _format_query_value(self, value: object) -> str:
+        if isinstance(value, bool):
+            return str(value).lower()
+        if isinstance(value, str):
+            return value
+        if isinstance(value, SequenceABC):
+            return ",".join(str(item) for item in value)
+        return str(value)
+
+    def _set_param(self, params: Dict[str, str], key: str, value: object) -> None:
+        if value is not None:
+            params[key] = self._format_query_value(value)
+
+    def _set_body_value(self, body: Dict[str, object], key: str, value: object) -> None:
+        if value is not None:
+            body[key] = value
+
+    def _remove_elements_list(
+        self, remove_elements: Optional[Sequence[str]]
+    ) -> Optional[Sequence[str]]:
+        if remove_elements is None:
+            return None
+        if isinstance(remove_elements, str):
+            return [
+                selector.strip()
+                for selector in remove_elements.split(",")
+                if selector.strip()
+            ]
+        return list(remove_elements)
+
+    def _build_params(self, options: ScreenshotOptions) -> Dict[str, str]:
+        params: Dict[str, str] = {}
+
+        self._set_param(params, "url", options.url)
+        self._set_param(params, "width", options.width)
+        self._set_param(params, "height", options.height)
+        self._set_param(params, "fullPage", options.full_page)
+        self._set_param(params, "type", options.type)
+        self._set_param(params, "quality", options.quality)
+        self._set_param(params, "colorScheme", options.color_scheme)
+        self._set_param(params, "waitUntil", options.wait_until)
+        self._set_param(params, "waitForSelector", options.wait_for_selector)
+        self._set_param(params, "delay", options.delay)
+        self._set_param(params, "blockAds", options.block_ads)
+        self._set_param(params, "removeCookieBanners", options.remove_cookie_banners)
+        self._set_param(params, "cssInject", options.css_inject)
+        self._set_param(params, "jsInject", options.js_inject)
+        self._set_param(params, "stealthMode", options.stealth_mode)
+        self._set_param(params, "devicePixelRatio", options.device_pixel_ratio)
+        self._set_param(params, "timezone", options.timezone)
+        self._set_param(params, "locale", options.locale)
+        self._set_param(params, "cacheTtl", options.cache_ttl)
+        self._set_param(params, "preloadFonts", options.preload_fonts)
+        self._set_param(params, "removeElements", options.remove_elements)
+        self._set_param(params, "removePopups", options.remove_popups)
+        self._set_param(params, "mockupDevice", options.mockup_device)
+        self._set_param(params, "geoLatitude", options.geo_latitude)
+        self._set_param(params, "geoLongitude", options.geo_longitude)
+        self._set_param(params, "geoAccuracy", options.geo_accuracy)
+        return params
+
+    def _build_body(self, options: ScreenshotOptions) -> Dict[str, object]:
+        body: Dict[str, object] = {}
+
+        self._set_body_value(body, "url", options.url)
+        self._set_body_value(body, "html", options.html)
+        self._set_body_value(body, "width", options.width)
+        self._set_body_value(body, "height", options.height)
+        self._set_body_value(body, "fullPage", options.full_page)
+        self._set_body_value(body, "type", options.type)
+        self._set_body_value(body, "quality", options.quality)
+        self._set_body_value(body, "colorScheme", options.color_scheme)
+        self._set_body_value(body, "waitUntil", options.wait_until)
+        self._set_body_value(body, "waitForSelector", options.wait_for_selector)
+        self._set_body_value(body, "delay", options.delay)
+        self._set_body_value(body, "blockAds", options.block_ads)
+        self._set_body_value(
+            body,
+            "removeCookieBanners",
+            options.remove_cookie_banners,
+        )
+        self._set_body_value(body, "cssInject", options.css_inject)
+        self._set_body_value(body, "jsInject", options.js_inject)
+        self._set_body_value(body, "stealthMode", options.stealth_mode)
+        self._set_body_value(body, "devicePixelRatio", options.device_pixel_ratio)
+        self._set_body_value(body, "timezone", options.timezone)
+        self._set_body_value(body, "locale", options.locale)
+        self._set_body_value(body, "cacheTtl", options.cache_ttl)
+        self._set_body_value(body, "preloadFonts", options.preload_fonts)
+        self._set_body_value(
+            body,
+            "removeElements",
+            self._remove_elements_list(options.remove_elements),
+        )
+        self._set_body_value(body, "removePopups", options.remove_popups)
+        self._set_body_value(body, "mockupDevice", options.mockup_device)
+
+        if options.geo_latitude is not None and options.geo_longitude is not None:
+            geo_location: Dict[str, object] = {
+                "latitude": options.geo_latitude,
+                "longitude": options.geo_longitude,
+            }
+            self._set_body_value(geo_location, "accuracy", options.geo_accuracy)
+            body["geoLocation"] = geo_location
+
+        return body
+
+    def _header_int(self, headers: httpx.Headers, key: str) -> int:
+        value = headers.get(key)
+        if value is None:
+            return 0
+        try:
+            return int(value)
+        except ValueError:
+            return 0
+
+    def _int_from_body(self, value: object) -> int:
+        if value is None:
+            return 0
+        if isinstance(value, bool):
+            return int(value)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str):
+            try:
+                return int(value)
+            except ValueError:
+                return 0
+        try:
+            return int(str(value))
+        except (TypeError, ValueError):
+            return 0
+
+    def _parse_metadata(self, headers: httpx.Headers) -> ScreenshotMetadata:
+        return ScreenshotMetadata(
+            credits_remaining=self._header_int(headers, "x-credits-remaining"),
+            screenshot_id=headers.get("x-screenshot-id", ""),
+            duration_ms=self._header_int(headers, "x-duration-ms"),
+        )
+
+    def _handle_error(self, response: httpx.Response) -> NoReturn:
+        try:
+            body = response.json()
+        except ValueError:
+            raise ScreenshotAPIError(
+                f"HTTP {response.status_code}: {response.reason_phrase}",
+                response.status_code,
+                "unknown_error",
+            )
+
+        if not isinstance(body, MappingABC):
+            raise ScreenshotAPIError(
+                f"HTTP {response.status_code}: {response.reason_phrase}",
+                response.status_code,
+                "unknown_error",
+            )
+
+        message = str(body.get("error", body.get("message", "Unknown error")))
+
+        if response.status_code == 401:
+            raise AuthenticationError(message)
+        elif response.status_code == 402:
+            balance = body.get("balance", body.get("creditBalance", 0))
+            raise InsufficientCreditsError(message, self._int_from_body(balance))
+        elif response.status_code == 403:
+            raise InvalidAPIKeyError(message)
+        elif response.status_code == 500:
+            raise ScreenshotFailedError(
+                str(body.get("message", body.get("error", "Screenshot failed")))
+            )
+        else:
+            raise ScreenshotAPIError(message, response.status_code, "unknown_error")
+
+    def screenshot(self, options: ScreenshotOptionsInput) -> ScreenshotResult:
+        """Take a screenshot synchronously. Returns image bytes and metadata."""
+        coerced = self._coerce_options(options)
+        self._validate_options(coerced)
+
+        try:
+            with httpx.Client(
+                timeout=self._timeout,
+                transport=self._transport,
+            ) as client:
+                if coerced.html is not None:
+                    response = client.post(
+                        f"{self._base_url}/api/v1/screenshot",
+                        json=self._build_body(coerced),
+                        headers={"x-api-key": self._api_key},
+                    )
+                else:
+                    response = client.get(
+                        f"{self._base_url}/api/v1/screenshot",
+                        params=self._build_params(coerced),
+                        headers={"x-api-key": self._api_key},
+                    )
+        except httpx.RequestError as exc:
+            raise NetworkError(f"Request failed: {exc}") from exc
+
+        if response.status_code >= 400:
+            self._handle_error(response)
+
+        return ScreenshotResult(
+            image=response.content,
+            metadata=self._parse_metadata(response.headers),
+            content_type=response.headers.get("content-type", "image/png"),
+        )
+
+    async def async_screenshot(
+        self, options: ScreenshotOptionsInput
+    ) -> ScreenshotResult:
+        """Take a screenshot asynchronously. Returns image bytes and metadata."""
+        coerced = self._coerce_options(options)
+        self._validate_options(coerced)
+
+        try:
+            async with httpx.AsyncClient(
+                timeout=self._timeout,
+                transport=self._async_transport,
+            ) as client:
+                if coerced.html is not None:
+                    response = await client.post(
+                        f"{self._base_url}/api/v1/screenshot",
+                        json=self._build_body(coerced),
+                        headers={"x-api-key": self._api_key},
+                    )
+                else:
+                    response = await client.get(
+                        f"{self._base_url}/api/v1/screenshot",
+                        params=self._build_params(coerced),
+                        headers={"x-api-key": self._api_key},
+                    )
+        except httpx.RequestError as exc:
+            raise NetworkError(f"Request failed: {exc}") from exc
+
+        if response.status_code >= 400:
+            self._handle_error(response)
+
+        return ScreenshotResult(
+            image=response.content,
+            metadata=self._parse_metadata(response.headers),
+            content_type=response.headers.get("content-type", "image/png"),
+        )
+
+    def save(
+        self,
+        options: ScreenshotOptionsInput,
+        path: Union[str, Path],
+    ) -> ScreenshotMetadata:
+        """Take a screenshot and save it to a file. Returns metadata."""
+        result = self.screenshot(options)
+        Path(path).write_bytes(result.image)
+        return result.metadata
+
+    async def async_save(
+        self,
+        options: ScreenshotOptionsInput,
+        path: Union[str, Path],
+    ) -> ScreenshotMetadata:
+        """Take a screenshot asynchronously and save it to a file."""
+        result = await self.async_screenshot(options)
+        Path(path).write_bytes(result.image)
+        return result.metadata

screenshotapi/errors.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+
+class ScreenshotAPIError(Exception):
+    def __init__(self, message: str, status: int, code: str) -> None:
+        super().__init__(message)
+        self.status = status
+        self.code = code
+
+
+class AuthenticationError(ScreenshotAPIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 401, "authentication_error")
+
+
+class InsufficientCreditsError(ScreenshotAPIError):
+    def __init__(self, message: str, balance: int) -> None:
+        super().__init__(message, 402, "insufficient_credits")
+        self.balance = balance
+
+
+class InvalidAPIKeyError(ScreenshotAPIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 403, "invalid_api_key")
+
+
+class ScreenshotFailedError(ScreenshotAPIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 500, "screenshot_failed")
+
+
+class NetworkError(ScreenshotAPIError):
+    def __init__(self, message: str) -> None:
+        super().__init__(message, 0, "network_error")

screenshotapi/types.py

@@ -0,0 +1,53 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal, Optional, Sequence
+
+ScreenshotFormat = Literal["png", "jpeg", "webp", "pdf"]
+ColorScheme = Literal["light", "dark"]
+WaitUntil = Literal["load", "domcontentloaded", "networkidle0", "networkidle2"]
+MockupDevice = Literal["browser", "iphone", "macbook"]
+
+@dataclass
+class ScreenshotOptions:
+    url: Optional[str] = None
+    width: Optional[int] = None
+    height: Optional[int] = None
+    full_page: Optional[bool] = None
+    type: Optional[ScreenshotFormat] = None
+    quality: Optional[int] = None
+    color_scheme: Optional[ColorScheme] = None
+    wait_until: Optional[WaitUntil] = None
+    wait_for_selector: Optional[str] = None
+    delay: Optional[int] = None
+    block_ads: Optional[bool] = None
+    remove_cookie_banners: Optional[bool] = None
+    html: Optional[str] = None
+    css_inject: Optional[str] = None
+    js_inject: Optional[str] = None
+    stealth_mode: Optional[bool] = None
+    device_pixel_ratio: Optional[int] = None
+    timezone: Optional[str] = None
+    locale: Optional[str] = None
+    cache_ttl: Optional[int] = None
+    preload_fonts: Optional[bool] = None
+    remove_elements: Optional[Sequence[str]] = None
+    remove_popups: Optional[bool] = None
+    mockup_device: Optional[MockupDevice] = None
+    geo_latitude: Optional[float] = None
+    geo_longitude: Optional[float] = None
+    geo_accuracy: Optional[float] = None
+
+
+@dataclass
+class ScreenshotMetadata:
+    credits_remaining: int
+    screenshot_id: str
+    duration_ms: int
+
+
+@dataclass
+class ScreenshotResult:
+    image: bytes
+    metadata: ScreenshotMetadata
+    content_type: str

screenshotapi_to-1.0.0.dist-info/METADATA

@@ -0,0 +1,311 @@
+Metadata-Version: 2.4
+Name: screenshotapi-to
+Version: 1.0.0
+Summary: Official Python SDK for ScreenshotAPI.
+Project-URL: Homepage, https://screenshotapi.to
+Project-URL: Documentation, https://screenshotapi.to/docs
+Project-URL: Pricing, https://screenshotapi.to/pricing
+Project-URL: Repository, https://github.com/miketromba/screenshotapi-python
+Project-URL: Issues, https://github.com/miketromba/screenshotapi-python/issues
+Project-URL: Support, https://screenshotapi.to
+Author-email: ScreenshotAPI <support@screenshotapi.to>
+Maintainer-email: ScreenshotAPI <support@screenshotapi.to>
+License: MIT License
+        
+        Copyright (c) 2026 ScreenshotAPI
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: api,capture,html-to-image,screenshot,screenshotapi,webpage,website-thumbnail
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+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: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Multimedia :: Graphics :: Capture :: Screen Capture
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Requires-Dist: httpx<1.0,>=0.24.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy<1.15,>=1.8; extra == 'dev'
+Requires-Dist: ruff>=0.8; extra == 'dev'
+Requires-Dist: twine>=5.0; extra == 'dev'
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# screenshotapi
+
+Official typed Python SDK for
+[ScreenshotAPI](https://screenshotapi.to?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk),
+the hosted screenshot API for turning URLs or HTML into PNG, JPEG, WebP, or PDF
+captures.
+
+## Install
+
+```bash
+pip install screenshotapi-to
+```
+
+Python 3.8+ is supported. The distribution package is `screenshotapi-to`, the
+import package is `screenshotapi`, and the package ships `py.typed` metadata for
+type checkers.
+
+## Authentication
+
+Create an API key in the ScreenshotAPI dashboard, then keep it in an environment
+variable:
+
+```bash
+export SCREENSHOTAPI_KEY="sk_live_your_key_here"
+```
+
+The SDK sends your key in the `x-api-key` header. Keep API keys on the server;
+do not expose them in browser bundles or mobile apps.
+
+## First Screenshot
+
+```python
+import os
+
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+metadata = client.save(
+    {
+        "url": "https://example.com",
+        "width": 1440,
+        "height": 900,
+    },
+    "screenshot.png",
+)
+
+print(f"Screenshot ID: {metadata.screenshot_id}")
+print(f"Credits remaining: {metadata.credits_remaining}")
+```
+
+## Usage
+
+### Initialize the Client
+
+```python
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(
+    "sk_live_your_key_here",
+    base_url="https://screenshotapi.to",
+    timeout=60.0,
+)
+```
+
+### Capture Bytes
+
+```python
+from screenshotapi import ScreenshotOptions
+
+result = client.screenshot(
+    ScreenshotOptions(
+        url="https://example.com",
+        full_page=True,
+        type="webp",
+        quality=90,
+        color_scheme="dark",
+    )
+)
+
+image_bytes = result.image
+content_type = result.content_type
+credits_remaining = result.metadata.credits_remaining
+```
+
+Plain dictionaries are also supported:
+
+```python
+result = client.screenshot(
+    {
+        "url": "https://example.com",
+        "full_page": True,
+        "type": "webp",
+    }
+)
+```
+
+### Async Capture
+
+```python
+import asyncio
+import os
+
+from screenshotapi import ScreenshotAPI
+
+client = ScreenshotAPI(os.environ["SCREENSHOTAPI_KEY"])
+
+
+async def main() -> None:
+    result = await client.async_screenshot({"url": "https://example.com"})
+    print(f"Duration: {result.metadata.duration_ms}ms")
+
+    await client.async_save({"url": "https://example.com"}, "screenshot.png")
+
+
+asyncio.run(main())
+```
+
+## Advanced Options
+
+```python
+result = client.screenshot(
+    {
+        "url": "https://example.com/dashboard",
+        "width": 1280,
+        "height": 720,
+        "device_pixel_ratio": 2,
+        "full_page": False,
+        "type": "webp",
+        "quality": 85,
+        "color_scheme": "dark",
+        "wait_until": "networkidle0",
+        "wait_for_selector": ".ready",
+        "delay": 500,
+        "block_ads": True,
+        "remove_cookie_banners": True,
+        "remove_popups": True,
+        "remove_elements": [".newsletter", "#cookie-banner"],
+        "css_inject": "body { caret-color: transparent; }",
+        "js_inject": "window.scrollTo(0, 0)",
+        "stealth_mode": True,
+        "timezone": "America/New_York",
+        "locale": "en-US",
+        "cache_ttl": 3600,
+        "preload_fonts": True,
+        "geo_latitude": 40.7128,
+        "geo_longitude": -74.0060,
+        "geo_accuracy": 25,
+    }
+)
+```
+
+HTML rendering uses `POST /api/v1/screenshot` automatically:
+
+```python
+result = client.screenshot(
+    {
+        "html": "<html><body><h1>Invoice #123</h1></body></html>",
+        "type": "pdf",
+    }
+)
+```
+
+Supported options:
+
+| Python option | API parameter | Notes |
+|---|---|---|
+| `url` | `url` | Required unless `html` is provided |
+| `html` | `html` | Raw HTML, sent with POST |
+| `width`, `height` | `width`, `height` | Viewport size |
+| `full_page` | `fullPage` | Capture full scrollable page |
+| `type` | `type` | `png`, `jpeg`, `webp`, or `pdf` |
+| `quality` | `quality` | JPEG/WebP quality, 1-100 |
+| `color_scheme` | `colorScheme` | `light` or `dark` |
+| `wait_until` | `waitUntil` | `load`, `domcontentloaded`, `networkidle0`, `networkidle2` |
+| `wait_for_selector` | `waitForSelector` | CSS selector to wait for |
+| `delay` | `delay` | Extra delay in milliseconds |
+| `block_ads` | `blockAds` | Remove ads before capture |
+| `remove_cookie_banners` | `removeCookieBanners` | Remove common consent banners |
+| `css_inject`, `js_inject` | `cssInject`, `jsInject` | Inject CSS or JavaScript before capture |
+| `stealth_mode` | `stealthMode` | Enable anti-bot fingerprint masking |
+| `device_pixel_ratio` | `devicePixelRatio` | `1`, `2`, or `3` |
+| `timezone`, `locale` | `timezone`, `locale` | Browser emulation settings |
+| `cache_ttl` | `cacheTtl` | Cache identical captures for N seconds |
+| `preload_fonts` | `preloadFonts` | Preload Google Fonts before capture |
+| `remove_elements` | `removeElements` | CSS selectors to remove |
+| `remove_popups` | `removePopups` | Remove common overlays and modals |
+| `mockup_device` | `mockupDevice` | `browser`, `iphone`, or `macbook` frame |
+| `geo_latitude`, `geo_longitude`, `geo_accuracy` | `geoLocation` or geo query params | Browser geolocation override |
+
+## Error Handling
+
+```python
+from screenshotapi import (
+    AuthenticationError,
+    InsufficientCreditsError,
+    InvalidAPIKeyError,
+    NetworkError,
+    ScreenshotAPI,
+    ScreenshotAPIError,
+    ScreenshotFailedError,
+)
+
+client = ScreenshotAPI("sk_live_your_key_here")
+
+try:
+    client.screenshot({"url": "https://example.com"})
+except AuthenticationError:
+    print("Missing API key")
+except InvalidAPIKeyError:
+    print("Invalid or revoked API key")
+except InsufficientCreditsError as exc:
+    print(f"No credits remaining. Balance: {exc.balance}")
+except ScreenshotFailedError as exc:
+    print(f"Screenshot failed: {exc}")
+except NetworkError as exc:
+    print(f"Could not reach ScreenshotAPI: {exc}")
+except ScreenshotAPIError as exc:
+    print(f"ScreenshotAPI error {exc.status} ({exc.code}): {exc}")
+```
+
+## Examples
+
+Runnable examples live in `examples/`:
+
+- `script_usage.py` for one-off scripts and cron jobs
+- `fastapi_app.py` for FastAPI endpoints
+- `django_view.py` for Django views
+- `flask_app.py` for Flask routes
+
+## Pricing and Free Tier
+
+ScreenshotAPI includes
+[200 free screenshots per month](https://screenshotapi.to/pricing?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+with no credit card required. Paid subscriptions and credit packs are available
+when you need more volume.
+
+## Links
+
+- [Documentation](https://screenshotapi.to/docs?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Screenshot API reference](https://screenshotapi.to/docs/api/screenshot?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Pricing](https://screenshotapi.to/pricing?utm_source=pypi&utm_medium=python-sdk&utm_campaign=sdk-readme&ref=python-sdk)
+- [Support](mailto:support@screenshotapi.to?subject=Python%20SDK%20support)
+
+## License
+
+MIT

screenshotapi_to-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+screenshotapi/__init__.py,sha256=kOQCcuSuzokMuG8gkKX0_Rgfd9aiPhP35qG-HpaFggU,763
+screenshotapi/client.py,sha256=cPMA52l7mJvwM5R92lgYyK8ogdhRl3aZDslLE1nNVHw,13135
+screenshotapi/errors.py,sha256=SZ3j657JzN-VBS0BzK22J-RQzBfP9xTFZBpkzn9ULBo,1049
+screenshotapi/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+screenshotapi/types.py,sha256=5SovilgY7QJjN4SjW0gYJR4Wb0iB-Qwp3rvtLqaAEg0,1667
+screenshotapi_to-1.0.0.dist-info/METADATA,sha256=Aw3aBCJNEMWgznzLaczcP0Y-56Odk7dzS7KdvOmeC44,10183
+screenshotapi_to-1.0.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+screenshotapi_to-1.0.0.dist-info/licenses/LICENSE,sha256=Tl6YDdBdkKGtgT2UyDDDvrxAcZw2PEhy6GvuMzhtlvU,1070
+screenshotapi_to-1.0.0.dist-info/RECORD,,

screenshotapi_to-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

screenshotapi_to-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ScreenshotAPI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.