README.md

---

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.