metadata

title: Page Screenshot API
emoji: 📸
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
license: other

📸 Page Screenshot API

Professional web page screenshot service built with Node.js and Puppeteer, optimized for Hugging Face Spaces with full-page support and flexible authentication.

🚀 Live Demo

API Endpoint: https://your-username-page-shot.hf.space/screenshot
Demo Interface: https://your-username-page-shot.hf.space/demo
Health Check: https://your-username-page-shot.hf.space/

🔐 Authentication Options

Option 1: Custom API Key (Recommended)

Set API_KEY environment variable in Space settings for secure access:

# With API key authentication
curl -X POST https://your-space.hf.space/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-here" \
  -d '{"url": "https://example.com", "fullPage": true}' \
  --output screenshot.jpg

Option 2: Open Access Mode

If no API_KEY is set, the API runs in open access mode:

# Open access (no authentication)
curl -X POST https://your-space.hf.space/screenshot \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "width": 1280, "height": 720}' \
  --output screenshot.jpg

Option 3: Private Space with HF Token

For private spaces, use HuggingFace access token:

# Private space access
curl -X POST https://your-space.hf.space/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer hf_your_token_here" \
  -d '{"url": "https://example.com"}' \
  --output screenshot.jpg

📊 API Parameters

Parameter	Type	Default	Range	Description
`url`	string	required	-	Target webpage URL (must start with http/https)
`width`	number	1280	100-1600	Screenshot width in pixels
`height`	number	720	100-1200	Screenshot height in pixels
`quality`	number	75	10-100	JPEG quality percentage (JPEG only)
`fullPage`	boolean	false	-	NEW: Capture full page length (long screenshots)
`format`	string	"jpeg"	jpeg/png	NEW: Output format (jpeg or png)

🆕 New Features in v1.5.0

📜 Full Page Screenshots

Capture entire webpage including content below the fold:

// Capture full page length
const response = await fetch('/screenshot', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': 'Bearer your-api-key'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    fullPage: true,  // 🆕 Captures entire page height
    format: 'png'    // 🆕 PNG format for better quality
  })
});

🖼️ Multiple Image Formats

Choose between JPEG (smaller size) and PNG (better quality):

# PNG format (lossless, larger file)
curl -X POST https://your-space.hf.space/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"url": "https://example.com", "format": "png"}' \
  --output screenshot.png

# JPEG format (compressed, smaller file)
curl -X POST https://your-space.hf.space/screenshot \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key" \
  -d '{"url": "https://example.com", "format": "jpeg", "quality": 85}' \
  --output screenshot.jpg

🔄 Response Examples

Success Response

HTTP/1.1 200 OK
Content-Type: image/jpeg  # or image/png
Content-Length: 245760

[Binary image data]

Authentication Error

{
  "error": "Unauthorized",
  "message": "Valid API key required. Please provide API key in Authorization header or x-api-key header.",
  "hint": "Use \"Authorization: Bearer YOUR_API_KEY\" or \"x-api-key: YOUR_API_KEY\""
}

Server Busy Response

{
  "status": "busy",
  "error": "Server is currently overloaded",
  "cpuUsage": "96%",
  "queueLength": 3
}

🛠️ Features

✅ Full Page Screenshots - Capture entire webpage length
✅ Multiple Formats - JPEG (compressed) and PNG (lossless) support
✅ Flexible Authentication - API key, open access, or HF token
✅ Global Font Support - Renders CJK, Arabic, Emoji fonts correctly
✅ Queue Management - Handles concurrent requests efficiently
✅ CPU Monitoring - Automatic load balancing
✅ Rate Limiting - Prevents abuse (100 req/15min)
✅ Error Handling - Comprehensive error responses
✅ Demo Interface - Built-in testing UI with auth detection
✅ Health Monitoring - Status endpoint for monitoring

🔧 Setup Instructions

Step 1: Configure Authentication (Optional)

# In HuggingFace Space Settings → Variables
API_KEY=sk-your-secure-random-key-here

Step 2: Deploy to HuggingFace Spaces

Create new Space with Docker SDK
Upload all files to Space repository
Set environment variables if needed
Space will auto-deploy

Step 3: Test the API

Visit the demo page: https://your-space.hf.space/demo

📈 Monitoring Endpoints

Health Check

curl https://your-space.hf.space/
# Returns API info and authentication status

Server Status

curl https://your-space.hf.space/status
# Returns CPU usage, active requests, queue status

🚨 Rate Limits & Performance

Metric	Limit	Notes
Requests	100/15min	Per IP address
Concurrent	3 requests	Server queue management
CPU Threshold	95%	Auto-rejects when overloaded
Timeout	15 seconds	Per screenshot request
Max Dimensions	1600x1200	Viewport size limits

🔒 Security & License

Proprietary License: Commercial use requires separate license
Non-Commercial Use: Educational and personal use permitted
API Security: Optional API key authentication
Resource Protection: Built-in rate limiting and queue management

🌍 Global Font Support

Optimized for international websites with support for:

CJK Languages: Chinese, Japanese, Korean
RTL Languages: Arabic, Hebrew
Emoji & Symbols: Full Unicode emoji support
Latin Scripts: European languages with proper rendering

🛡️ Production Recommendations

Enable API Key: Set API_KEY environment variable for production
Use Private Space: For sensitive or commercial use
Implement Retry Logic: Handle busy server responses
Monitor Usage: Use /status endpoint for health checks
Choose Format Wisely: JPEG for photos, PNG for graphics/text

📚 Documentation

📄 License

Proprietary Non-Commercial License - See LICENSE for full terms.

✅ Educational and personal use
❌ Commercial use without license
❌ Redistribution or modification

🤝 Support

For commercial licensing, technical support, or feature requests, please contact the administrator.