ScreenshotAce API Documentation

1. Introduction

The ScreenshotAce API allows you to programmatically capture screenshots of websites using a REST API call. Both POST and GET request methods are supported.

2. Authentication

You need an API key to access the ScreenshotAce API. You must include this key in the x-api-key header.

x-api-key: YOUR_API_KEY

If you're interested in acquiring ScreenshotAce LLC and would like a trial API key, contact screenshotace[at]gmail.com.

3. Taking Screenshots

x-api-key: YOUR_API_KEY
Content-Type: application/json

{
    "url": "https://example.com", 
    "width": 1024,
    "height": 580,
    "type": "jpeg"
}

x-api-key: YOUR_API_KEY
Content-Type: application/json

https://api.screenshotace.com?responseType=binary&url=https://example.com

{
    "url": "https://cdn.screenshotace.com/images/bJCIm7fsQA.jpeg"
    "width": 1024,
    "height": 580
}

{
    "status_code": 400,
    "error_code": "RequestValidationError",
    "message": "The x value of the clip object was undefined. When clip is used, x must be defined."
}

4. Options

You can customize your screenshots using the following options. These can be included in the JSON request body for POST requests or as query parameters for GET requests.

5. Examples

5.1. cURL

POST Request

curl -X POST \
    https://api.screenshotace.com \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \
    -d '{ "url": "https://example.com" }'

Response

{
    "url": "https://cdn.screenshotace.com/images/puSIja6cdx.png",
    "width": 1280,
    "height": 720
}

GET Request

curl -X GET \
    https://api.screenshotace.com?width=320&height=480&responseType=binary&url=https://apple.com \
    -H 'x-api-key: YOUR_API_KEY' \
    -H 'Content-Type: application/json' \

Response (image as binary data)

5.2. Node.js

POST Request

import fetch from 'node-fetch';

const apiKey = process.env.SCREENSHOTACE_API_KEY; // Store your API key securely.
const apiEndpointUrl = 'https://api.screenshotace.com';

async function captureScreenshot() {
  if (!apiKey) {
    console.error('API key not found in environment variable SCREENSHOTACE_API_KEY');
    return;
  }

  const postData = {
    url: 'https://www.example.com',
    width: 800,
    height: 600,
    type: 'jpeg',
    responseType: 'json'
  };

  try {
    const response = await fetch(apiEndpointUrl, {
      method: 'POST',
      headers: {
        'x-api-key': apiKey,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(postData)
    });

    const data = await response.json();
    console.log('Response:', data);

    if (data.url) {
      console.log('Screenshot URL:', data.url);
    }    
  } catch (error) {
    console.error('Fetch error:', error);
  }
}

captureScreenshot();

Console Output

Response: {
  url: 'https://cdn.screenshotace.com/images/yWvEJsvVx0.jpeg',
  width: 800,
  height: 600
}
Screenshot URL: https://cdn.screenshotace.com/images/yWvEJsvVx0.jpeg

5.3. Hiding Specific Elements

Hiding Elements with hideSelectors

Many websites display cookie consent modals that can obscure the main content. Using the hideSelectors option, you can instruct the API to hide these elements before taking a screenshot. The following example shows how to target and hide a typical cookie policy modal.

POST Request Body using hideSelectors

{
    "url": "https://ubuntu.com/desktop/flavors",
    "hideSelectors": ["#modal"],
    "responseType": "binary" 
} 

Response

In the example below, the hideSelectors option was used to hide additional elements, like the navigation bars and the heading.

POST Request Body

{
    "url": "https://ubuntu.com/desktop/flavors",
    "hideSelectors": ["#modal", "#navigation", ".p-navigation", "h1"],
    "responseType": "binary" 
} 

Response