Skip to main content

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
  • JavaScript
  • Python
  • PHP
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
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

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

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
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
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
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