Quickstart

Master the Screenshothis API in under 5 minutes

Get your first screenshot

Capture your first screenshot and explore advanced features. You’ll go from zero to production-ready integration in under 5 minutes.

1. Create your account

   Sign up for a free account at screenshothis.com to get 100 free screenshots per month.

   You’ll be redirected to your dashboard immediately after registration

2. Generate your API key

   Navigate to API Keys in your dashboard and create your first API key.

   Your API keys use domain whitelisting for security—you can safely commit them to version control. Configure allowed domains in your dashboard to control where your key works.

3. Make your first request

   Test your API key with a simple screenshot request using any method below.

Your first screenshot

cURL

The quickest way to test the API:

curl -X GET "https://api.screenshothis.com/v1/screenshots/take?api_key=ss_test_1234567890abcdef&url=https://github.com" \
  -o screenshot.jpeg

Your screenshot saves as screenshot.jpeg in the current directory

JavaScript

Perfect for web applications and Node.js:

npm install @screenshothis/sdk

import { Screenshothis } from "@screenshothis/sdk";

const screenshothis = new Screenshothis();

async function takeScreenshot() {
  try {
    const imageData = await screenshothis.screenshots.take({
      apiKey: "ss_test_1234567890abcdef",
      url: "https://github.com"
    });

    // Save to file (Node.js)
    const fs = require('fs');
    fs.writeFileSync('screenshot.jpeg', Buffer.from(imageData));

    console.log('Screenshot saved successfully!');
  } catch (error) {
    console.error('Screenshot failed:', error.message);
  }
}

takeScreenshot();

Complete SDK Guide

For comprehensive documentation including error handling, tree-shaking, React/Vue examples, and all available options

Python

Ideal for data science and backend services:

import requests

try:
    response = requests.get(
        'https://api.screenshothis.com/v1/screenshots/take',
        params={
            'api_key': 'ss_test_1234567890abcdef',
            'url': 'https://github.com'
        }
    )

    response.raise_for_status()  # Raise an exception for bad responses

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

    print('Screenshot saved successfully!')

except requests.exceptions.RequestException as e:
    print(f'Screenshot failed: {e}')

You’ll see “Screenshot saved successfully!” when the image saves

PHP

Great for WordPress and Laravel integrations:

<?php
try {
    $params = http_build_query([
        'api_key' => 'ss_test_1234567890abcdef',
        'url' => 'https://github.com'
    ]);

    $url = 'https://api.screenshothis.com/v1/screenshots/take?' . $params;
    $context = stream_context_create([
        'http' => [
            'method' => 'GET',
            'timeout' => 30
        ]
    ]);

    $screenshot = file_get_contents($url, false, $context);

    if ($screenshot === false) {
        throw new Exception('Failed to capture screenshot');
    }

    file_put_contents('screenshot.jpeg', $screenshot);
    echo 'Screenshot saved successfully!';

} catch (Exception $e) {
    echo 'Screenshot failed: ' . $e->getMessage();
}
?>

Customize your screenshots

Control format, size, and behavior with these parameters:

Enhanced cURL

curl -X GET "https://api.screenshothis.com/v1/screenshots/take" \
  -G \
  -d "api_key=ss_test_1234567890abcdef" \
  -d "url=https://github.com" \
  -d "format=webp" \
  -d "quality=90" \
  -d "width=1920" \
  -d "height=1080" \
  -d "block_ads=true" \
  -d "block_cookie_banners=true" \
  -d "prefers_color_scheme=dark" \
  -d "is_cached=true" \
  -d "cache_ttl=7200" \
  -o screenshot.webp

Mobile device simulation

See how your website appears on mobile devices:

Mobile cURL

curl -X GET "https://api.screenshothis.com/v1/screenshots/take" \
  -G \
  -d "api_key=ss_test_1234567890abcdef" \
  -d "url=https://github.com" \
  -d "is_mobile=true" \
  -d "width=390" \
  -d "height=844" \
  -d "device_scale_factor=3" \
  -d "has_touch=true" \
  -d "format=webp" \
  -d "quality=85" \
  -o mobile-screenshot.webp

API parameters

Customize your screenshots with these parameters:

Required parameters

api_key · string · required

Your API key from the dashboard. Uses domain whitelisting for security—safe to commit to version control.

url · string · required

The website URL to screenshot. Must be a valid URL including protocol (http:// or https://).

Viewport and device settings

width · integer · default: "1920"

Viewport width in pixels. Range: 100-3840.

height · integer · default: "1080"

Viewport height in pixels. Range: 100-2160.

is_mobile · boolean · default: "false"

Simulate mobile device viewport and user agent.

is_landscape · boolean · default: "false"

Set device orientation to landscape when using mobile simulation.

has_touch · boolean · default: "false"

Enable touch input simulation for the device.

device_scale_factor · number · default: "1"

Device pixel ratio for high-DPI displays. Common values: 1, 1.5, 2, 3.

Image output settings

format · string · default: "jpeg"

Image format. Options: jpeg, png, webp.

quality · integer · default: "80"

Image quality for JPEG and WebP formats. Range: 20-100.

selector · string

CSS selector to screenshot a specific element instead of the full page.

Content filtering

block_ads · boolean · default: "false"

Block advertisements and tracking scripts for cleaner screenshots.

block_cookie_banners · boolean · default: "false"

Automatically dismiss cookie consent banners and privacy notices.

block_trackers · boolean · default: "false"

Block all trackers and third-party scripts.

Accessibility and preferences

prefers_color_scheme · string · default: "light"

Set color scheme preference. Options: light, dark.

prefers_reduced_motion · string · default: "no-preference"

Set motion preference for animations. Options: no-preference, reduce.

Caching settings

is_cached · boolean · default: "false"

Enable caching for this screenshot to improve performance on repeated requests.

cache_ttl · integer · default: "3600"

Cache time-to-live in seconds when caching is enabled. Range: 3600-31622400 (1 hour to 1 year).

cache_key · string

Custom cache key for grouping related screenshots. Use with is_cached=true.

Content filtering (NEW)

block_requests · string

Block specific URL patterns during page load. One pattern per line, supports wildcards.

*.doubleclick.net
*.googletagmanager.com
*/analytics/*

block_resources · array

Block specific resource types from loading. Available types: document, stylesheet, image, media, font, script, texttrack, xhr, fetch, prefetch, eventsource, websocket, manifest, signedexchange, ping, cspviolationreport, preflight, other.

# Block scripts and stylesheets for faster loading
-d "block_resources=script,stylesheet"

Advanced browser settings

headers · string

Custom HTTP headers in Name: Value format, one per line. Maximum size: 8KB.

Authorization: Bearer token
User-Agent: MyBot/1.0
X-Custom-Header: value

cookies · string

Custom cookies using Set-Cookie syntax, one per line. Maximum size: 4KB.

session_id=abc123; Domain=example.com; Path=/; Secure
user_pref=dark_mode; Max-Age=3600

bypass_csp · boolean · default: "false"

Bypass Content Security Policy restrictions. Use only when necessary for specific sites.

Security and size limits:

• Headers: Maximum 8KB total size
• Cookies: Maximum 4KB total size
• URL length: Maximum 2048 characters
• Request timeout: 30 seconds maximum

Response formats

Image response (default)

You receive the screenshot image directly as binary data:

curl "https://api.screenshothis.com/v1/screenshots/take?api_key=ss_test_1234567890abcdef&url=https://github.com" \
  -o screenshot.jpeg

Content-Type: image/jpeg, image/png, or image/webp based on your format parameter.

Error responses

When requests fail, you receive a JSON error response:

{
  "error": "Invalid API key",
  "requestId": "req_1234567890abcdef"
}

Common HTTP status codes:

• 400 - Bad request (invalid parameters)
• 403 - Forbidden (invalid API key or quota exceeded)
• 429 - Too many requests (rate limit exceeded)
• 500 - Internal server error

Test the API interactively

API Playground

Test the API with different URLs and parameters to see results instantly.

Try different parameters without writing code

Sample URLs for testing

Try these URLs to see different screenshot results:

• Modern website: https://screenshothis.com
• Code repository: https://github.com/screenshothis/screenshothis
• Documentation: https://docs.screenshothis.com
• News site: https://news.ycombinator.com

Real-world examples

Social media previews

Generate dynamic og:image tags for better social media sharing:

import { Screenshothis } from "@screenshothis/sdk";

async function generateSocialPreview(blogPostUrl: string, apiKey: string) {
  const screenshothis = new Screenshothis();

  try {
    const imageData = await screenshothis.screenshots.take({
      apiKey,
      url: blogPostUrl,
      width: 1200,
      height: 630,
      format: "jpeg",
      quality: 85
    });

    // Convert to base64 for immediate use
    const base64 = Buffer.from(imageData).toString('base64');
    return `data:image/jpeg;base64,${base64}`;
  } catch (error) {
    console.error('Failed to generate preview:', error.message);
    return null;
  }
}

// Usage in your application
const previewUrl = await generateSocialPreview("https://myblog.com/post", apiKey);
// Use in HTML: <meta property="og:image" content="data:image/jpeg;base64,..." />

Perfect for Twitter, LinkedIn, and Facebook sharing cards

Website thumbnails

Create thumbnails for link previews, portfolios, or dashboards:

import requests
from PIL import Image
from io import BytesIO

def create_thumbnail(website_url, api_key, thumbnail_size=(400, 300)):
    try:
        response = requests.get(
            'https://api.screenshothis.com/v1/screenshots/take',
            params={
                'api_key': api_key,
                'url': website_url,
                'width': '1920',
                'height': '1080',
                'format': 'png'
            },
            timeout=30
        )

        response.raise_for_status()

        # Create thumbnail using PIL
        image = Image.open(BytesIO(response.content))
        image.thumbnail(thumbnail_size, Image.Resampling.LANCZOS)

        return image

    except requests.exceptions.RequestException as e:
        print(f'Failed to create thumbnail: {e}')
        return None

# Usage
thumbnail = create_thumbnail('https://example.com', 'ss_test_1234567890abcdef')
if thumbnail:
    thumbnail.save('thumbnail.png')

Use WebP format for smaller file sizes in web applications

Visual regression testing

Capture screenshots for automated testing pipelines:

import { Screenshothis } from "@screenshothis/sdk";
import * as fs from 'fs';
import * as path from 'path';

class VisualTester {
  private screenshothis: Screenshothis;

  constructor(private apiKey: string) {
    this.screenshothis = new Screenshothis();
  }

  async captureBaseline(url: string, testName: string): Promise<string> {
    try {
      const imageData = await this.screenshothis.screenshots.take({
        apiKey: this.apiKey,
        url,
        width: 1920,
        height: 1080,
        format: "png",
        blockAds: true  // Consistent results
      });

      const filename = `baselines/${testName}.png`;
      fs.writeFileSync(filename, Buffer.from(imageData));

      console.log(`✅ Baseline saved: ${filename}`);
      return filename;

    } catch (error) {
      console.error(`❌ Failed to capture baseline: ${error.message}`);
      throw error;
    }
  }
}

// Usage in your test suite
const tester = new VisualTester('ss_test_1234567890abcdef');
await tester.captureBaseline('https://myapp.com/component', 'header-component');

Ideal for CI/CD pipelines and automated quality assurance

Direct URL rendering

The most efficient approach - construct the URL directly:

// Build screenshot URLs without making API calls
function buildScreenshotUrl(
  url: string,
  apiKey: string,
  options: Record<string, string | number | boolean> = {}
): string {
  const params = new URLSearchParams({
    api_key: apiKey,
    url: url,
    ...Object.fromEntries(
      Object.entries(options).map(([k, v]) => [k, String(v)])
    )
  });

  return `https://api.screenshothis.com/v1/screenshots/take?${params}`;
}

// Usage - instant, no async needed!
const screenshotUrl = buildScreenshotUrl("https://github.com", "ss_test_1234567890abcdef", {
  format: "png",
  width: 800,
  height: 600,
  block_ads: true
});

// Use directly in HTML
document.getElementById('myImage').src = screenshotUrl;
// Or in React: <img src={screenshotUrl} alt="Screenshot" />

React component example:

interface ScreenshotImageProps {
  url: string;
  apiKey: string;
  width?: number;
  height?: number;
  format?: 'jpeg' | 'png' | 'webp';
}

function ScreenshotImage({ url, apiKey, width = 800, height = 600, format = 'webp' }: ScreenshotImageProps) {
  const screenshotUrl = buildScreenshotUrl(url, apiKey, {
    width,
    height,
    format,
    block_ads: true
  });

  return (
    <img
      src={screenshotUrl}
      alt="Screenshot"
      loading="lazy"
      onError={(e) => console.error('Screenshot failed to load')}
    />
  );
}

// Usage
<ScreenshotImage
  url="https://example.com"
  apiKey="ss_test_1234567890abcdef"
  width={1200}
  height={630}
  format="webp"
/>

Much more efficient! The browser fetches the image directly - no intermediate processing needed

Next steps

API Reference

Explore all available parameters, response formats, and error handling

JavaScript SDK

Use our official TypeScript SDK with full type safety and error handling

Self-hosting

Run Screenshothis on your own infrastructure for complete control

OpenAPI Spec

Generate client libraries for any programming language