API Documentation

Everything you need to integrate SnapAPI into your application. Capture pixel-perfect screenshots with a simple REST API.

Introduction

SnapAPI is a high-performance screenshot API that lets you capture any webpage as an image. Built for developers who need reliable, fast, and accurate screenshots at scale.

🚀 Base URL

https://api.snapapi.pics/v1

Key Features

  • Full page screenshots with automatic scrolling
  • Custom viewport sizes (desktop, tablet, mobile)
  • Multiple formats: PNG, JPEG, WebP, PDF
  • JavaScript execution before capture
  • Dark mode and device emulation
  • Request blocking (ads, trackers, cookies)
  • Custom cookies and headers
  • Webhook callbacks for async processing

Authentication

All API requests require authentication using an API key. Include your key in the request header:

Header 
X-Api-Key: sk_live_your_api_key_here
⚠️ Keep Your Key Secret

Never expose your API key in client-side code. Always make API calls from your backend server.

API Key Types

Prefix Type Description
sk_live_ Production For production use, counts against your quota
sk_test_ Testing For development, limited functionality

Quick Start

Get started with SnapAPI in under a minute. Here's how to capture your first screenshot:

cURL 
curl -X POST https://api.snapapi.pics/v1/screenshot \
  -H "X-Api-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com",
    "format": "png",
    "width": 1920,
    "height": 1080
  }' \
  --output screenshot.png
JavaScript 
const response = await fetch('https://api.snapapi.pics/v1/screenshot', {
  method: 'POST',
  headers: {
    'X-Api-Key': 'sk_live_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    url: 'https://example.com',
    format: 'png',
    width: 1920,
    height: 1080
  })
});

const imageBlob = await response.blob();
Python 
import requests

response = requests.post(
    'https://api.snapapi.pics/v1/screenshot',
    headers={
        'X-Api-Key': 'sk_live_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'url': 'https://example.com',
        'format': 'png',
        'width': 1920,
        'height': 1080
    }
)

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

SDKs & Libraries

Official client libraries to make integration even easier:

📦
JavaScript / TypeScript
npm install @snapapi/sdk
🐍
Python
pip install snapapi
🐘
PHP
composer require snapapi/sdk
🔷
Go
go get github.com/Sleywill/snapapi-go
🟣
Kotlin / Android
implementation("dev.snapapi:sdk:1.1.0")
🍎
Swift / iOS
.package(url: "...snapapi-swift", from: "1.1.0")

Take Screenshot

POST /v1/screenshot

Capture a screenshot of the specified URL and return the image.

Parameters

Parameter Type Required Description
url string Required The URL to capture. Must be a valid HTTP/HTTPS URL.
format string Optional Output format: png, jpeg, webp, pdf. Default: png
width integer Optional Viewport width in pixels (100-3840). Default: 1920
height integer Optional Viewport height in pixels (100-2160). Default: 1080
fullPage boolean Optional Capture the full scrollable page. Default: false
quality integer Optional Image quality 1-100 (JPEG/WebP only). Default: 80
scale number Optional Device scale factor 0.5-3 (retina). Default: 1
delay integer Optional Delay in ms before capture (0-10000). Default: 0
timeout integer Optional Max wait time in ms (1000-60000). Default: 30000
darkMode boolean Optional Emulate dark mode preference. Default: false
mobile boolean Optional Emulate mobile device. Default: false
selector string Optional CSS selector to capture specific element.
waitForSelector string Optional Wait for element to appear before capture.
javascript string Optional JavaScript code to execute before capture.
blockAds boolean Optional Block ads and trackers. Default: false
hideCookieBanners boolean Optional Hide cookie consent banners. Default: false
cookies array Optional Array of cookies to set before navigation.
headers object Optional Custom HTTP headers for the request.

Response

The API returns the screenshot image directly with the appropriate Content-Type header.

✅ Success (200)

Returns binary image data with headers:
Content-Type: image/png (or jpeg, webp, application/pdf)
X-Screenshot-Duration: 523 (processing time in ms)

Error Responses

JSON Error 
{
  "error": {
    "code": "INVALID_URL",
    "message": "The provided URL is not valid",
    "details": {
      "url": "not-a-url"
    }
  }
}

Batch Screenshots

POST /v1/screenshot/batch

Capture multiple screenshots in a single request. Pro plan and above.

Request 
{
  "urls": [
    "https://example.com",
    "https://example.org",
    "https://example.net"
  ],
  "format": "png",
  "width": 1920,
  "height": 1080,
  "webhookUrl": "https://your-server.com/webhook"
}

Batch requests are processed asynchronously. You'll receive a job ID immediately, and results will be sent to your webhook URL when complete.

Async Mode

For long-running captures or when you want non-blocking behavior, use async mode:

Request 
{
  "url": "https://example.com",
  "async": true,
  "webhookUrl": "https://your-server.com/webhook"
}

The API immediately returns a job ID:

Response 
{
  "jobId": "job_abc123xyz",
  "status": "processing",
  "estimatedTime": 2000
}

Viewport Options

Customize the browser viewport to capture responsive designs:

Common Presets

Device Width Height Scale
Desktop HD 1920 1080 1
Desktop 4K 3840 2160 1
MacBook Pro 1440 900 2
iPad Pro 1024 1366 2
iPhone 14 Pro 393 852 3
Pixel 7 412 915 2.625
Mobile Screenshot Example 
{
  "url": "https://example.com",
  "width": 393,
  "height": 852,
  "scale": 3,
  "mobile": true
}

Wait Strategies

Control when the screenshot is taken with various wait options:

Wait for Network Idle

By default, SnapAPI waits until the network is idle (no requests for 500ms). This works well for most pages.

Wait for Selector

Wait for a specific element to appear:

JSON 
{
  "url": "https://example.com",
  "waitForSelector": ".content-loaded"
}

Fixed Delay

Add a fixed delay after page load:

JSON 
{
  "url": "https://example.com",
  "delay": 2000  // Wait 2 seconds
}

JavaScript Execution

Execute custom JavaScript before capturing the screenshot:

Example: Accept Cookies 
{
  "url": "https://example.com",
  "javascript": "document.querySelector('.cookie-accept')?.click();"
}
Example: Remove Elements 
{
  "url": "https://example.com",
  "javascript": "document.querySelectorAll('.ad, .popup, .modal').forEach(el => el.remove());"
}

Request Blocking

Block unwanted requests to speed up capture and get cleaner screenshots:

Block Ads & Trackers 
{
  "url": "https://example.com",
  "blockAds": true,
  "hideCookieBanners": true
}

The blockAds option blocks:

  • Google Ads, DoubleClick
  • Facebook Pixel, Analytics
  • Common ad networks
  • Tracking scripts

Cookies & Headers

Set custom cookies and headers to capture authenticated pages:

Setting Cookies 
{
  "url": "https://example.com/dashboard",
  "cookies": [
    {
      "name": "session",
      "value": "abc123",
      "domain": "example.com"
    }
  ]
}
Custom Headers 
{
  "url": "https://api.example.com/page",
  "headers": {
    "Authorization": "Bearer your-token",
    "X-Custom-Header": "value"
  }
}

Error Handling

SnapAPI returns structured error responses with helpful details:

Code HTTP Status Description
INVALID_URL 400 The URL is malformed or not accessible
INVALID_PARAMS 400 One or more parameters are invalid
UNAUTHORIZED 401 Missing or invalid API key
FORBIDDEN 403 API key doesn't have permission
QUOTA_EXCEEDED 429 Monthly quota has been exceeded
RATE_LIMITED 429 Too many requests, slow down
TIMEOUT 504 Page took too long to load
CAPTURE_FAILED 500 Screenshot capture failed

Rate Limits

Rate limits vary by plan:

Plan Requests/Second Concurrent Monthly Quota
Free 1 1 100
Starter 5 3 5,000
Pro 10 10 25,000
Enterprise 50 50 Unlimited

Rate limit headers are included in every response:

Response Headers 
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 9
X-RateLimit-Reset: 1640000000
X-Quota-Remaining: 24950

Webhooks

Receive notifications when async screenshots are complete:

Webhook Payload 
{
  "event": "screenshot.completed",
  "jobId": "job_abc123xyz",
  "status": "success",
  "url": "https://example.com",
  "imageUrl": "https://cdn.snapapi.pics/screenshots/abc123.png",
  "duration": 1523,
  "timestamp": "2024-01-15T10:30:00Z"
}
🔒 Webhook Security

All webhook requests include a signature header X-Signature that you can verify using your API key.

Examples

Social Media Preview

Generate Open Graph images for social sharing:

cURL 
curl -X POST https://api.snapapi.pics/v1/screenshot \
  -H "X-Api-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-site.com/blog/post",
    "width": 1200,
    "height": 630,
    "format": "png",
    "selector": ".og-image-content"
  }' --output og-image.png

PDF Generation

Convert web pages to PDF documents:

cURL 
curl -X POST https://api.snapapi.pics/v1/screenshot \
  -H "X-Api-Key: sk_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/invoice/123",
    "format": "pdf",
    "fullPage": true
  }' --output invoice.pdf

E-commerce Product Shots

Capture product pages with consistent styling:

JavaScript 
const products = ['product-1', 'product-2', 'product-3'];

for (const id of products) {
  const response = await fetch('https://api.snapapi.pics/v1/screenshot', {
    method: 'POST',
    headers: {
      'X-Api-Key': 'sk_live_xxx',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      url: `https://shop.example.com/product/${id}`,
      selector: '.product-image',
      width: 800,
      height: 800,
      blockAds: true
    })
  });

  // Save the image...
}

Need Help?

Can't find what you're looking for? We're here to help.

support@snapapi.pics