/v1/screenshot

Capture a screenshot of any public URL.

GET https://api.urlpix.com/v1/screenshot

Parameters

Parameter	Type	Default	Range	Required	Description
url	string	—	—	Yes	Target URL (http/https only, no private IPs)
format	string	png	png, jpg, webp, pdf	No	Output format
width	integer	1280	1–3840	No	Viewport width in pixels
height	integer	800	1–3840	No	Viewport height in pixels
quality	integer	80	1–100	No	JPEG/WebP compression quality
deviceScale	float	1.0	1.0–3.0	No	Device pixel ratio (DPR)
delay	integer	0	0–10000	No	Wait time (ms) after page load
timeout	integer	30000	1–60000	No	Total timeout in ms
fullPage	boolean	false	—	No	Capture full scrollable page
waitForSelector	string	—	CSS selector	No	Wait for element before capture
clip	string	—	x,y,w,h	No	Clip region (comma-separated integers)
blockCookies	boolean	false	—	No	Block cookie consent banners (Starter+)
blockAds	boolean	false	—	No	Block advertisements (Starter+)
darkMode	boolean	false	—	No	Emulate prefers-color-scheme: dark (Starter+)
device	string	—	See presets	No	Device emulation preset (Pro+)
customCSS	string	—	—	No	Inject custom CSS before capture (Pro+)
customJS	string	—	—	No	Execute custom JavaScript before capture (Pro+)
response	string	—	json	No	Return JSON metadata instead of image
api_key	string	—	—	No	API key (alternative to header)

PDF-Only Parameters

These parameters apply only when format=pdf:

Parameter	Type	Default	Range	Required	Description
pageSize	string	letter	a4, letter, legal, tabloid, a3, a5	No	PDF page size (Starter+)
landscape	boolean	false	—	No	Landscape orientation (Starter+)
margin	string	—	top,right,bottom,left	No	Page margins in mm (Starter+)
headerTemplate	string	—	HTML string	No	PDF header HTML template (Starter+)
footerTemplate	string	—	HTML string	No	PDF footer HTML template (Starter+)
printBackground	boolean	true	—	No	Print background graphics (Starter+)
scale	float	1.0	0.1–2.0	No	PDF render scale (Starter+)

Authentication

Pass your API key via the X-API-Key header (recommended) or the api_key query parameter.

Response

Binary response (default): The image/PDF bytes with appropriate Content-Type header.

JSON response (response=json): Metadata object with the target URL, image URL, dimensions, format, file size, and cache timestamp (cachedAt — unix ms when cached, or null if freshly rendered).

Response Headers

Header	Description
X-Render-Time	Render duration in milliseconds
X-Image-Size	Image file size in bytes
X-Cache	HIT (served from cache) or MISS (freshly rendered)

Examples

curl

# Basic PNG screenshot
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o screenshot.png

# Full page WebP with retina
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&format=webp&fullPage=true&deviceScale=2&quality=90" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o full-retina.webp

# Clip a specific region
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&clip=0,0,800,600" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o clipped.png

# Wait for dynamic content
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&waitForSelector=.loaded&delay=1000" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o dynamic.png

JavaScript (fetch)

const params = new URLSearchParams({
  url: 'https://example.com',
  format: 'webp',
  width: '1920',
  height: '1080',
  quality: '90',
})

const response = await fetch(
  `https://api.urlpix.com/v1/screenshot?${params}`,
  { headers: { 'X-API-Key': 'sk_live_YOUR_KEY' } }
)

const blob = await response.blob()
const imageUrl = URL.createObjectURL(blob)

Node.js

import fs from 'fs'

const params = new URLSearchParams({
  url: 'https://example.com',
  format: 'png',
  width: '1920',
  height: '1080',
  deviceScale: '2',
})

const response = await fetch(
  `https://api.urlpix.com/v1/screenshot?${params}`,
  { headers: { 'X-API-Key': process.env.URLPIX_API_KEY } }
)

const buffer = Buffer.from(await response.arrayBuffer())
fs.writeFileSync('screenshot.png', buffer)
console.log(`Size: ${buffer.length} bytes`)

Advanced Parameters

Cookie & Ad Blocking (Starter+)

# Block cookie banners and ads
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&blockCookies=true&blockAds=true" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o clean.png

Dark Mode (Starter+)

curl "https://api.urlpix.com/v1/screenshot?url=https://github.com&darkMode=true" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o dark.png

Device Presets (Pro+)

Preset	Width	Height	Scale
iphone-15	393	852	3
ipad-pro	1024	1366	2
pixel-8	412	915	2.625
galaxy-s24	360	780	3

curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&device=iphone-15" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o mobile.png

Custom CSS & JS Injection (Pro+)

# Hide a specific element with custom CSS
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&customCSS=.banner%7Bdisplay:none%7D" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o no-banner.png

# Execute JS before screenshot
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&customJS=document.querySelector('.popup').remove()" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o no-popup.png

PDF Options (Starter+)

# A4 landscape PDF with margins
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&format=pdf&pageSize=a4&landscape=true&margin=10,15,10,15" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o document.pdf

# PDF with custom header/footer
curl "https://api.urlpix.com/v1/screenshot?url=https://example.com&format=pdf&headerTemplate=%3Cdiv%20style%3D%22font-size%3A10px%22%3EPage%20%3Cspan%20class%3D%22pageNumber%22%3E%3C%2Fspan%3E%3C%2Fdiv%3E&printBackground=true&scale=0.8" \
  -H "X-API-Key: sk_live_YOUR_KEY" \
  -o styled.pdf

Error Responses

Status	Description
400	Missing url, invalid format, out-of-range parameter, or private IP
401	Missing or invalid API key
502	Renderer unavailable
504	Render timeout exceeded

Caching

Screenshots are cached automatically. Cache TTL depends on your plan:

Plan	TTL
Free	7 days
Starter	14 days
Pro	30 days
Business	60 days

The cache key is derived from: url, width, height, format, quality, fullPage, deviceScale, delay, and clip.