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.

Create your account

You’ll be redirected to your dashboard immediately after registration

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.

Make your first request

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

Your first screenshot

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

Customize your screenshots

Control format, size, and behavior with these parameters:

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:

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.

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

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

Getting Started

SDKs

Self-Hosting

API Reference

Health & Monitoring

Quickstart

Get your first screenshot

Your first screenshot

Customize your screenshots

Mobile device simulation

API parameters

Required parameters

Viewport and device settings

Image output settings

Content filtering

Accessibility and preferences

Caching settings

Content filtering (NEW)

Advanced browser settings

Response formats

Image response (default)

Error responses

Test the API interactively

API Playground

Sample URLs for testing

Real-world examples

Next steps

API Reference

JavaScript SDK

Self-hosting

OpenAPI Spec

Getting Started

SDKs

Self-Hosting

API Reference

Health & Monitoring

​Get your first screenshot

​Your first screenshot

​Customize your screenshots

​Mobile device simulation

​API parameters

​Required parameters

​Viewport and device settings

​Image output settings

​Content filtering

​Accessibility and preferences

​Caching settings

​Content filtering (NEW)

​Advanced browser settings

​Response formats

​Image response (default)

​Error responses

​Test the API interactively

API Playground

​Sample URLs for testing

​Real-world examples

​Next steps

API Reference

JavaScript SDK

Self-hosting

OpenAPI Spec

Get your first screenshot

Your first screenshot

Customize your screenshots

Mobile device simulation

API parameters

Required parameters

Viewport and device settings

Image output settings

Content filtering

Accessibility and preferences

Caching settings

Content filtering (NEW)

Advanced browser settings

Response formats

Image response (default)

Error responses

Test the API interactively

Sample URLs for testing

Real-world examples

Next steps