---
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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```javascript
// 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):

```bash
# 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
```json
{
  "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
```json
{
  "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)
```bash
# In HuggingFace Space Settings → Variables
API_KEY=sk-your-secure-random-key-here
```

### Step 2: Deploy to HuggingFace Spaces
1. Create new Space with Docker SDK
2. Upload all files to Space repository
3. Set environment variables if needed
4. Space will auto-deploy

### Step 3: Test the API
Visit the demo page: `https://your-space.hf.space/demo`

## 📈 Monitoring Endpoints

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

### Server Status
```bash
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

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

## 📚 Documentation

- [API Authentication Guide](API_GUIDE.md)
- [Private Space Setup](PRIVATE_SPACE_GUIDE.md)  
- [Environment Variables](HF_SPACES_ENV_GUIDE.md)
- [Deployment Guide](DEPLOYMENT_GUIDE.md)

## 📄 License

**Proprietary Non-Commercial License** - See [LICENSE](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.