rendshot 0.3.0

Official Python SDK for RendShot — HTML-to-image rendering and URL screenshots

rendshot

Official Python SDK for RendShot — HTML-to-image rendering and URL screenshots.

Installation

pip install rendshot

Quick Start

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

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

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

Parameter	Type	Default	Description
api_key	str	required	Your RendShot API key (rs_live_...)
base_url	str	https://api.rendshot.ai	API base URL
trust_env	bool | None	auto	Honor HTTP_PROXY / system proxy. None (default) auto-detects: False for localhost, True for remote URLs. See System proxies on macOS.

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

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"

System proxies on macOS

httpx reads the macOS system proxy via urllib.request.getproxies(). When a proxy like Surge or Shadowrocket is active, httpx will (by default) route even http://localhost traffic through the proxy — which typically returns a 503 Connection Closed HTML page instead of reaching your local API server.

To match the behavior of curl and Node's undici, this SDK automatically disables proxy auto-detection when base_url points at localhost, 127.0.0.1, ::1, or 0.0.0.0. If you need the opposite — e.g. you actually want localhost traffic to go through a proxy — pass trust_env=True explicitly:

RendshotClient(api_key="rs_live_...", base_url="http://localhost:4000", trust_env=True)

Conversely, pass trust_env=False to disable system-proxy reading entirely for a remote base URL.

License

MIT