Quickstart

Get started with Pageshot in three simple steps.

Get an API key from your dashboard

Choose what to capture (URL, HTML, or Markdown)

Send a POST request to /v1/capture

Your First Capture

Capture any website as a PNG image:

curl -X POST https://api.pageshot.com/v1/capture \
  -H "Content-Type: application/json" \
  -H "X-Access-Key: your_api_key" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "full_page": true
  }' \
  --output capture.png

const fs = require('fs');
const https = require('https');

const options = {
  hostname: 'api.pageshot.com',
  path: '/v1/capture',
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-Access-Key': process.env.PAGESHOT_KEY
  }
};

const req = https.request(options, (res) => {
  res.pipe(fs.createWriteStream('capture.png'));
});

req.write(JSON.stringify({
  url: 'https://example.com',
  format: 'png',
  full_page: true
}));

req.end();

import os
import requests

response = requests.post(
    'https://api.pageshot.com/v1/capture',
    headers={
        'Content-Type': 'application/json',
        'X-Access-Key': os.environ['PAGESHOT_KEY']
    },
    json={
        'url': 'https://example.com',
        'format': 'png',
        'full_page': True
    },
    timeout=60
)

with open('capture.png', 'wb') as f:
    f.write(response.content)

The API returns the PNG image data directly in the response body with Content-Type: image/png.

Common Use Cases

Website Preview

Perfect for social sharing, link previews, or monitoring:

{
  "url": "https://yoursite.com/blog/post",
  "format": "png",
  "viewport": { "width": 1200, "height": 630 },
  "full_page": false
}

Email Template Preview

Render HTML directly:

{
  "html": "<html><head><style>body{font-family:Arial}</style></head><body><h1>Invoice</h1></body></html>",
  "format": "png",
  "viewport": { "width": 600, "height": 800 }
}

Documentation Card

Convert markdown to an image:

{
  "markdown": "# Getting Started\n\nInstall with npm...",
  "format": "png",
  "viewport": { "width": 800, "height": 400 }
}

Response Format

The API returns binary image data with appropriate headers:

HTTP/1.1 200 OK
Content-Type: image/png
Content-Length: 245678
X-Request-Id: req_abc123
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59

<binary PNG data>

Output Formats

Choose from multiple image and video formats:

{
  "url": "https://example.com",
  "format": "jpeg",
  "quality": 85
}

Image Formats:

png - Best quality, larger files (default)
jpeg - Smaller files with quality control (1-100)
webp - Modern format, good compression
pdf - Multi-page documents

Video Formats:

mp4 - Standard video format with quality control
gif - Animated GIF for social media
webm - Native Playwright output, fastest

Record a Video

Capture a 5-second video of any webpage:

{
  "url": "https://example.com",
  "format": "mp4",
  "motion": {
    "type": "still",
    "duration": 5
  }
}

Scrolling Animation

Create a smooth scrolling video:

{
  "url": "https://example.com/long-page",
  "format": "gif",
  "motion": {
    "type": "scroll",
    "duration": 10,
    "scroll_by": 800,
    "easing": "ease_in_out"
  },
  "video": {
    "fps": 20,
    "scale": 0.5
  }
}

Troubleshooting

Authentication Error (401)

Verify your API key is correct
Check the X-Access-Key header is set
Ensure the key hasn't been revoked

Timeout Error

Increase the timeout: "wait": { "timeout_ms": 60000 }
Check if the target URL is accessible
Try with wait_until: ["domcontentloaded"] instead of networkidle

SSRF Blocked

The URL might be pointing to a private network
Use a publicly accessible URL
Or route through a proxy: "auth": { "proxy": "http://your-proxy.com" }

Invalid Request

Check your JSON syntax
Ensure only one of url, html, or markdown is provided
Verify format is one of: png, jpeg, webp, pdf

Next Steps

Authentication - Secure your API keys
Input Sources - URL, HTML, and Markdown options
Viewports - Control screen size
Capture Options - Full API reference

Quickstart

On this page