Documentation

Everything you need to integrate FreeScreenshot API. One endpoint, zero config, 100% free.

Quick Start

Send a URL, receive an image. The simplest possible API call:

GET

https://freescreenshot.dpdns.org/take?url=https://google.com

That's it. The response is a JPEG image you can use directly in an <img> tag, save to disk, or process further.

Usage Examples

HTML

<img src="https://freescreenshot.dpdns.org/take?url=https://example.com" alt="Screenshot" />

JavaScript

const response = await fetch('https://freescreenshot.dpdns.org/take?url=https://example.com&format=png');
const blob = await response.blob();

// Create an image element
const img = document.createElement('img');
img.src = URL.createObjectURL(blob);
document.body.appendChild(img);

cURL

curl -o screenshot.png "https://freescreenshot.dpdns.org/take?url=https://example.com&format=png"

Python

import requests

response = requests.get('https://freescreenshot.dpdns.org/take', params={
    'url': 'https://example.com',
    'format': 'png',
    'full_page': 'true'
})

with open('screenshot.png', 'wb') as f:
    f.write(response.content)

Authentication

FreeScreenshot API is completely free and requires no authentication. There are no API keys, tokens, or accounts to manage. Just make requests directly.

Base URL

All API requests should be made to:

https://freescreenshot.dpdns.org

GET /take

Capture a screenshot by passing parameters as URL query strings.

Request

GET /take?url=https://example.com&format=png&full_page=true

All parameters from the parameter reference below are supported as query string values.

POST /take

Send parameters as a JSON body for cleaner integration when passing many options.

Request

curl -X POST https://freescreenshot.dpdns.org/take \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "full_page": true,
    "viewport_width": 1920,
    "dark_mode": true
  }'

Essential Parameters

Parameter	Type	Default	Description
`url`	string	required	The full URL of the page to screenshot. Must include protocol (http/https).
`format`	string	jpeg	Output image format. Options: `jpeg`, `png`, `webp`

Viewport Parameters

Control the browser viewport dimensions and pixel density.

Parameter	Type	Default	Description
`viewport_width`	number	1280	Browser viewport width in pixels. Range: 320 - 3840
`viewport_height`	number	1024	Browser viewport height in pixels. Range: 240 - 8000
`device_scale_factor`	number	1	Device pixel ratio for high-DPI screenshots. Range: 1 - 5

Image Parameters

Fine-tune the output image quality and dimensions.

Parameter	Type	Default	Description
`quality`	number	80	Image quality for JPEG and WebP. Range: 1 - 100. Ignored for PNG.
`omit_background`	boolean	false	Make the page background transparent. Only works with PNG format.

Capture Parameters

Control what gets captured and how.

Parameter	Type	Default	Description
`full_page`	boolean	false	Capture the entire scrollable page from top to bottom, not just the viewport.
`selector`	string	-	CSS selector to capture only a specific element on the page.
`wait_for_selector`	string	-	Wait for this CSS selector to appear in the DOM before capturing.
`hide_selectors`	string	-	Comma-separated list of CSS selectors to hide before capturing.

Selector example: &take?url=https://example.com&selector=.hero-section captures only the element matching .hero-section.

Emulation Parameters

Parameter	Type	Default	Description
`dark_mode`	boolean	false	Emulate `prefers-color-scheme: dark` so websites render in dark mode.

Blocking Parameters

Parameter	Type	Default	Description
`block_resources`	string	-	Comma-separated resource types to block. Options: `image`, `stylesheet`, `script`, `font`, `media`. Speeds up capture by skipping heavy resources.

Wait & Timing Parameters

Parameter	Type	Default	Description
`delay`	number	0	Wait time in milliseconds after page load before capturing. Useful for animations. Range: 0 - 10000
`timeout`	number	30000	Maximum time in milliseconds to wait for the page to load. Range: 1000 - 60000

Clip Region Parameters

Capture a rectangular region of the page by specifying pixel coordinates.

Parameter	Type	Default	Description
`clip_x`	number	-	X offset of the clip region in pixels.
`clip_y`	number	-	Y offset of the clip region in pixels.
`clip_width`	number	-	Width of the clip region in pixels.
`clip_height`	number	-	Height of the clip region in pixels.

Note: All four clip parameters must be provided together. If any are missing, the clip region is ignored and the full viewport is captured.

Response

A successful response returns the raw image binary with the appropriate Content-Type header.

Header	Value
`Content-Type`	`image/jpeg`, `image/png`, or `image/webp`
`Cache-Control`	`public, max-age=600`

Error Codes

Status	Meaning	Cause
`400`	Bad Request	Missing `url` parameter or invalid URL format.
`429`	Too Many Requests	Rate limit exceeded. See Rate Limits.
`500`	Server Error	Screenshot capture failed. The target site may be down or timing out.

Errors return a JSON body:

{ "error": "Missing required parameter: url" }

Rate Limits

To keep the service free and available for everyone, requests are rate limited to 30 requests per minute per IP address.

If you exceed the limit, the API returns a 429 status. Simply wait a minute and retry.

Caching

Identical requests are cached for 10 minutes. If you request the same URL with the same parameters within that window, you'll receive the cached result instantly.

The cache key includes all parameters (URL, format, quality, viewport, etc.), so changing any parameter results in a fresh capture.