Overview

Themefisher Screencap is a high-performance serverless API that captures webpage screenshots with customizable dimensions, quality settings, and output formats. Built for reliability and scalability on Vercel's serverless infrastructure.

⚡

Serverless Architecture

Deployed on Vercel with optimized memory (1024MB) and 60-second timeout for complex pages

🎨

Customizable Output

Control viewport dimensions, device scale factor, image quality, and format (PNG/JPEG)

🔒

Secure Access

Optional secret-based authentication to protect your API from unauthorized usage

Quick Start

Basic Request

HTTP GET

GET /api/capture?url=https://example.com

With Custom Dimensions

HTTP GET

GET /api/capture?url=https://example.com&width=1920&height=1080

cURL Example

Bash

curl -o screenshot.png \
  "https://your-domain.vercel.app/api/capture?url=https://example.com&width=1920&height=1080"

JavaScript Example

JavaScript

const response = await fetch(
  `/api/capture?url=${encodeURIComponent('https://example.com')}&width=1920&height=1080`
);

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

// Use the image
document.querySelector('img').src = imageUrl;

API Reference

Endpoint

GET /api/capture

Captures a screenshot of the specified URL and returns the image as binary data.

Query Parameters

Parameter	Type	Required	Description	Default
url	string	✅ Yes	The URL of the webpage to capture	-
width	number	No	Viewport width in pixels	Browser default
height	number	No	Viewport height in pixels	Browser default
type	string	No	Image format: `png` or `jpeg`	png
quality	number	No	Image quality (0-100, JPEG only)	80
scaleFactor	number	No	Device scale factor for high-DPI displays	1
timeout	number	No	Page load timeout in milliseconds	30000
delay	number	No	Delay before screenshot in milliseconds	300
secret	string	Conditional	Authentication secret (required if `SECRET` env var is set)	-

Response

Success (200 OK)

Returns the screenshot as binary image data with appropriate Content-Type header:

image/png for PNG format
image/jpeg for JPEG format

Error Responses

Status Code	Description
403	Forbidden - Invalid or missing secret authentication
500	Internal Server Error - Screenshot capture failed (timeout, invalid URL, etc.)

Advanced Usage

High-Resolution Screenshots

Capture retina-quality screenshots using the scaleFactor parameter:

HTTP GET

GET /api/capture?url=https://example.com&width=1920&height=1080&scaleFactor=2

This produces a 3840x2160 image with crisp, high-DPI rendering.

Optimized JPEG Output

For smaller file sizes, use JPEG format with custom quality:

HTTP GET

GET /api/capture?url=https://example.com&type=jpeg&quality=85

Handling Slow Pages

For pages with heavy JavaScript or slow loading times, increase the timeout and delay:

HTTP GET

GET /api/capture?url=https://example.com&timeout=60000&delay=2000

Authenticated Requests

When the API is protected with a secret, include it in your requests:

HTTP GET

GET /api/capture?url=https://example.com&secret=your-secret-key

⚠️ Security Note

Always use HTTPS when transmitting secret keys. Consider using environment variables or secure vaults to store your API secret.

Common Use Cases

Social Media Previews

Generate Open Graph images for dynamic content with standardized dimensions (1200x630).

PDF Generation

Capture full-page screenshots for archival or PDF conversion workflows.

Automated Testing

Visual regression testing by comparing screenshots across deployments.

Content Thumbnails

Generate preview thumbnails for blog posts, landing pages, or user-generated content.

Monitoring & Alerts

Capture screenshots of error pages or monitoring dashboards for incident reports.

Email Campaigns

Create visual previews of web pages for email marketing campaigns.

Technical Details

Technology Stack

Runtime: Node.js 20+
Browser Engine: Puppeteer Core with Sparticuz Chromium
Platform: Vercel Serverless Functions
Memory: 1024MB allocated per function
Timeout: 60 seconds maximum execution time

Performance Considerations

First request may experience cold start (~2-3 seconds)
Subsequent requests benefit from warm function instances
Large viewports and high scale factors increase processing time
JPEG format typically produces smaller files than PNG

Limitations

Maximum execution time: 60 seconds (Vercel function limit)
Pages requiring authentication may not render correctly
JavaScript-heavy SPAs may need increased delay parameter
Some websites block headless browsers via bot detection

Local Development

Prerequisites

Bash

# Install dependencies
yarn install

# Install Vercel CLI globally
npm install -g vercel

Environment Setup

Create a .env file (optional):

.env

# Optional: Protect API with secret
SECRET=your-secret-key-here

Run Development Server

Bash

vercel dev

The API will be available at http://localhost:3000/api/capture

Run Tests

Bash

yarn test