API Reference

Screenshot API converts any URL or HTML snippet into a screenshot or PDF with a single HTTP request. Authenticate with an API key, POST your payload, receive binary image or PDF bytes.

Quickstart

Step 1 — Create a free account at https://screenshotapis.org/signup. Your first API key is created automatically.

Step 2 — Copy your API key from the dashboard. It looks like sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

Step 3 — Make your first call:

curl -X POST https://screenshotapis.org/v1/screenshot \
  -H "X-Api-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "format": "png"}' \
  --output screenshot.png

Authentication

Pass your API key in the X-Api-Key request header on every call. You can also pass it as a Bearer token: Authorization: Bearer sk_live_….

X-Api-Key: sk_live_your_key_here

API keys are shown once on creation. If you lose a key, revoke it in the dashboard and create a new one. Keys are stored as one-way hashes — we can never recover the original value.

POST /v1/screenshot

POSThttps://screenshotapis.org/v1/screenshot

Returns raw image bytes (image/png, image/jpeg, or image/webp) on success.

Request body (JSON)

Field	Type	Default	Description
url	string	—	required* URL to render. Must be http or https.
html	string	—	required* Raw HTML to render. Max 5 MB.
format	string	`png`	Output format: `png` · `jpeg` · `webp`
viewport_width	int	`1280`	Browser width in px (100–3840)
viewport_height	int	`800`	Browser height in px (100–2160)
full_page	bool	`false`	Capture the full scrollable page height
quality	int	`null`	Compression quality 1–100 (jpeg / webp only)
delay_ms	int	`0`	Wait N ms after page load (0–10 000). Useful for animations.
selector	string	`null`	CSS selector — capture only that element
dark_mode	bool	`false`	Enable `prefers-color-scheme: dark`
device_scale_factor	float	`1.0`	Pixel ratio (0.5–3.0). Use `2.0` for retina.

* Exactly one of url or html must be provided.

Example — OG image from HTML

curl -X POST https://screenshotapis.org/v1/screenshot \
  -H "X-Api-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<div style=\"width:1200px;height:630px;background:#0d6efd;color:#fff;display:flex;align-items:center;justify-content:center;font-size:3rem\">My Article Title</div>",
    "viewport_width": 1200,
    "viewport_height": 630,
    "device_scale_factor": 2
  }' \
  --output og-image.png

Example — retina full-page screenshot

curl -X POST https://screenshotapis.org/v1/screenshot \
  -H "X-Api-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com","full_page":true,"device_scale_factor":2}' \
  --output fullpage.png

POST /v1/pdf

POSThttps://screenshotapis.org/v1/pdf

Returns raw PDF bytes (application/pdf) on success with a Content-Disposition: attachment; filename=render.pdf header.

Request body (JSON)

Field	Type	Default	Description
url	string	—	required* URL to render
html	string	—	required* Raw HTML to render. Max 5 MB.
format	string	`A4`	Paper size: `A4` · `Letter` · `Legal` · `A3` · `Tabloid`
landscape	bool	`false`	Landscape orientation
margin_top	string	`1cm`	Top margin (CSS units: `1cm`, `20px`, etc.)
margin_right	string	`1cm`	Right margin
margin_bottom	string	`1cm`	Bottom margin
margin_left	string	`1cm`	Left margin
print_background	bool	`true`	Include background colors and images
display_header_footer	bool	`false`	Show header and footer
header_template	string	`""`	HTML for the page header (Chromium template)
footer_template	string	`""`	HTML for the page footer

Example — HTML to PDF invoice

curl -X POST https://screenshotapis.org/v1/pdf \
  -H "X-Api-Key: sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<html><body><h1>Invoice #42</h1><p>Amount due: $100</p></body></html>",
    "format": "A4",
    "margin_top": "2cm",
    "margin_bottom": "2cm"
  }' \
  --output invoice.pdf

GET /v1/usage

GEThttps://screenshotapis.org/v1/usage

Returns current usage statistics for the authenticated user.

Response (JSON)

{
  "plan": "growth",
  "credits_remaining": 5843,
  "renders_today": 12,
  "renders_this_month": 157,
  "renders_total": 2841
}

Error codes

Status	When it happens
400	Invalid URL, blocked scheme (not http/https), or private IP (SSRF guard)
401	Missing or invalid `X-Api-Key`
402	Insufficient credits — upgrade or buy a credit pack
422	Render failed: page error, JS crash, selector not found, or timeout
429	Rate limit exceeded — see rate limits

Error bodies follow the format: {"detail": "Human-readable message."}

On a 422, the credit is refunded — you are never charged for a failed render.

Rate limits

Rate limits apply per API key. The window is a 60-second sliding window.

Plan	Requests / minute	Monthly credits
free	10	100
starter	30	2,000
growth	60	6,000
business	120	25,000
scale	300	75,000

When a rate limit is hit the API returns HTTP 429 with header Retry-After: 60.

Response headers

Header	Description
X-Render-Time-Ms	How long the render took in milliseconds
X-Credits-Remaining	Credits left on your account after this render
X-Request-Id	Unique request ID — include in support requests