Screenshotly Python SDK

Official typed Python client for the Screenshotly API. It uses the Python standard library for HTTP requests and supports Python 3.10+.

pip install screenshotly

import os

from screenshotly import BinaryCapture, Screenshotly

client = Screenshotly(os.environ["SCREENSHOTLY_API_KEY"])
capture = client.capture(
    "https://example.com",
    format="webp",
    full_page=True,
)

if isinstance(capture, BinaryCapture):
    capture.save(capture.filename or "capture.webp")
else:
    print(capture.url)

capture() returns BinaryCapture for normal responses and StoredCapture when storage={"enabled": True} is requested. Use capture_bytes() when your integration always expects raw bytes.

Errors and retries

from screenshotly import ScreenshotlyError

try:
    client.capture("https://example.com")
except ScreenshotlyError as error:
    print(error.status, error.code, error.retry_after)

The client retries HTTP 429 and 5xx responses twice by default and respects Retry-After. Network failures are surfaced because retrying after a lost response can create an ambiguous duplicate capture. Configure timeout, max_retries, and max_retry_delay on the client, or pass RequestOptions to one call.

Asynchronous jobs

import uuid

accepted = client.create_job(
    "https://example.com",
    format="png",
    idempotency_key=str(uuid.uuid4()),
)
job = client.wait_for_job(accepted.id, timeout=120)
if job.status == "SUCCEEDED":
    print(job.result_url)

Batch and job operations require the corresponding paid plan. The SDK also exposes create_batch, get_job, list_jobs, and cancel_job.

Keep API keys on the server. Never embed them in browser JavaScript or a public mobile bundle.

Development

python -m pip install -e '.[dev]'
ruff check .
mypy screenshotly tests
python -m unittest discover -s tests -v
python -m build

Licensed under the MIT License.