What image format does the API return?

The API returns PNG images encoded as base64 data URLs in the JSON response.

Are there rate limits?

URLPixel Open Source does not enforce rate limits by default. You can implement your own rate limiting if needed.

How long does screenshot generation take?

Screenshot generation typically takes 2-8 seconds depending on the website complexity and selected quality profile.

Can I capture mobile versions of websites?

Yes, use the 'mobile' quality profile to capture websites as they appear on mobile devices.

Documentation

Quick Deploy

Deploy to Railway View on GitHub

Need Production Features?

URLPixel offers 10x performance, site organization, and professional support.

Start Free Compare Features →

Quick Deploy

Railway GitHub

Need Production Features?

URLPixel offers 10x performance & more.

Start Free

API Reference

Complete technical documentation

URLPixel Open Source provides a simple REST API for generating website screenshots. All endpoints return JSON responses with consistent error handling and detailed metadata.

Base URL: https://your-domain.com

Format: JSON

Quick Start Example

Generate a Screenshot

curl -X POST https://your-domain.com/screenshot \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "quality": "high",
    "fullPage": false,
    "removeAds": true
  }'

API Endpoints

Headers

Name	Required	Description
Content-Type	Required	Must be application/json
X-API-Key	Optional	API key for authentication (if configured)

Parameters

Name	Type	Required	Description
url	`string`	Required	The URL to capture. Must be a valid HTTP or HTTPS URL.
quality	`string`	Optional	Screenshot quality profile Default: `"standard"` Options: "standard", "high", "retina", "mobile"
wait	`number`	Optional	Additional wait time in milliseconds (1000-8000) Default: `"Smart wait time based on URL"`
fullPage	`boolean`	Optional	Capture full page height instead of viewport only
removeAds	`boolean`	Optional	Attempt to remove ads, cookie banners, and popups Default: `true`

Example Request

{
  "url": "https://example.com",
  "quality": "high",
  "fullPage": false,
  "removeAds": true
}

Example Response

{
  "success": true,
  "image": "data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...",
  "url": "https://example.com",
  "quality": "standard",
  "width": 1280,
  "height": 720,
  "fileSize": 145678,
  "processingTimeMs": 2500
}

Quality Profiles

standard

1280×720

Good quality for web previews and thumbnails

Scale Factor: 1x

Use Case: Website previews, social media thumbnails

high

1920×1080

High definition for detailed screenshots

Scale Factor: 1x

Use Case: Documentation, detailed captures

retina

2560×1440

Retina/HiDPI displays with double pixel density

Scale Factor: 2x

Use Case: High-DPI displays, print materials

mobile

375×667

Mobile viewport simulation

Scale Factor: 2x

Use Case: Mobile website testing, responsive design

Error Codes

400

Bad Request

Invalid URL format or missing required parameters

{
  "success": false,
  "error": "URL is required"
}

401

Unauthorized

Invalid or missing API key (when authentication is enabled)

{
  "error": "Invalid API key"
}

408

Request Timeout

Website took too long to load or respond

{
  "success": false,
  "error": "Navigation timeout - site took too long to load"
}

500

Internal Server Error

Screenshot generation failed or server error

{
  "success": false,
  "error": "Screenshot generation failed"
}

Authentication (Optional)

URLPixel Open Source supports optional API key authentication. When the API_KEY environment variable is set, all requests must include the API key in the headers.

Environment Configuration

API_KEY=your-secret-api-key

Request Headers

X-API-Key: your-secret-api-key

Authorization: Bearer your-secret-api-key