SCRNIFY.com API Documentation

This API allows you to capture screenshots and video recordings of web pages with customizable parameters.

Billing

Pricing is graduated within each billing period. The first 2,000 billable usage units cost €0.008 each. Each additional billable usage unit costs €0.005. These rates are marginal: the lower rate applies only above the breakpoint, while the first 2,000 billable usage units remain €0.008 each.

A successful non-cached screenshot is one usage unit. A successful video uses its requested duration in seconds. Screenshots and video seconds share one pool. Failures and successful cache hits do not consume usage units.

The lifetime trial checks prior lifetime usage before each request. While prior usage is below 100 units, the entire successful request is free; a request is never split at the boundary. For example, with 95 prior units, a successful 60-second video is entirely free, and paid metering starts with the next eligible request. Separately, with active billing, the first 100 usage units in each billing period are free before graduated rates apply. A billing period is the Stripe subscription anniversary period, not a calendar month.

For current worked examples, see Scrnify pricing or machine-readable pricing.

When billing is required, the API returns 402 Payment Required with billing_required for JSON responses.

Base URL

https://api.scrnify.com/capture

Authentication

There are two types of API keys available for authentication:

Simple API Key

Basic authentication using only the API key:

?key=your_api_key

Signed API Key

Enhanced security by signing requests. Requires both the API key and a signature:

?key=your_api_key&signature=generated_signature&cache_ttl=3600

Requirements for signed API keys:

• The signature must be 64 characters long
• cache_ttl parameter is required
• Signature must be generated using HMAC-SHA256

Generating Signatures

To generate a valid signature:

1. Create an HMAC-SHA256 hash of the remaining query string using your API key's secret
2. Convert the hash to a hexadecimal string

Example (Node.js):

const crypto = require('crypto')

function generateSignature(queryString, secret) {
    const hmac = crypto.createHmac('sha256', secret)
    hmac.update(queryString)
    return hmac.digest('hex')
}

// Example usage
const params = new URLSearchParams({
    key: 'your_api_key',
    url: 'https://example.com',
    type: 'image',
    format: 'png',
    width: '1920',
    height: '1080',
    cache_ttl: '3600',
})

const signature = generateSignature(params.toString(), 'your_api_secret')
params.append('signature', signature)

const finalUrl = `${baseUrl}?${params.toString()}`

Note: The signature verification will check both the encoded and decoded query strings to handle URL encoding differences.

Core Parameters

Parameter	Type	Required	Description
url	string	Yes	The URL of the webpage to capture (must be URL-encoded)
type	string	Yes	Type of capture: image or video
format	string	Yes	Output format (see Format Options below)
width	number	Yes	Viewport width in pixels
height	number	*	Viewport height in pixels. Required if fullPage=false, ignored if fullPage=true
fullPage	boolean	No	Whether to capture the full page length (default: false)
cache_ttl	number	**	Cache duration in seconds (max: 30 days). Required for signed API keys
output	string	No	Response mode: file (default) or json

Format Options

Image Formats

• webp: WebP format
• jpeg: JPEG format
  • Additional parameter: quality (1-100, default: 100)
• png: PNG format

Video Formats

• mp4: MP4 format
• webm: WebM format
• gif: Animated GIF format

Additional Parameters

Parameter	Type	Description
duration	number	Duration in seconds for video capture (default: 1, maximum supported: 60). Only applicable when type=video
waitUntil	string	Event to wait for before capture. Options:
		- firstPaint: When the first pixel is painted by the browser
		- firstContentfulPaint: When the first text, image, canvas, or SVG is painted
		- firstImagePaint: When the first image element is painted
		- firstMeaningfulPaintCandidate: When the browser first considers a meaningful paint might have occurred
		- firstMeaningfulPaint (default): When the primary content of the page is visible
		- DOMContentLoaded: When initial HTML is completely loaded and parsed
		- load: When the whole page and all dependent resources (images, styles) are finished loading
		- networkIdle: When there are no more than 0 network connections for at least 500ms
		- networkAlmostIdle: When there are no more than 2 network connections for at least 500ms
userAgent	string	Custom User-Agent string for the request
selector	string	CSS selector to capture a specific element. When provided, the API waits for the element to be visible and captures only that element instead of the viewport
blockCookieDefault	boolean	Whether to block cookies by default (default: true)
blockFilter	string	Custom filter rules using Adblock Plus / uBlock Origin syntax for blocking requests. See filter syntax documentation

Example Requests

Basic Screenshot

/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=png&width=1920&height=1080

Full Page JPEG Screenshot with Caching

/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=jpeg&width=1920&fullPage=true&quality=90&cache_ttl=3600

Signed API Key Request

/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=png&width=1920&height=1080&cache_ttl=3600&signature=YOUR_GENERATED_SIGNATURE

Element Screenshot with Selector

/capture?key=YOUR_API_KEY&url=https%3A%2F%2Fwww.example.com&type=image&format=png&width=1920&height=1080&selector=.hero-section

Response

JSON output

Set output=json to receive a JSON object after a new capture. The file value is the public asset URL, not file data:

{
    "request_id": "V1StGXR8_Z5jdHi6B-myT",
    "file": "https://assets.example.com/images/20260714/V1StGXR8_Z5jdHi6B-myT.png"
}

File output

With output=file, or when output is omitted, a successful request returns 307 Temporary Redirect with the asset URL in the Location header. Most HTTP clients follow that redirect and then receive the image or video bytes directly from the asset host. Disable automatic redirect following if you need to inspect the 307 response or Location header.

Cache hits also return 307 Temporary Redirect to the cached asset URL, including requests that specify output=json.

On error, the API returns an appropriate HTTP error status. Error response format can depend on output mode and error type.

Error Handling

The API will return appropriate HTTP status codes for different error scenarios:

• 400: Invalid parameters or missing required fields
• 401: Invalid API key or signature
• 403: Unauthorized access
• 404: Resource not found
• 500: Server errors

Best Practices

1. Always URL-encode the target URL
2. Set appropriate viewport dimensions for your use case
3. Consider using fullPage=true for capturing long web pages
4. Adjust JPEG quality for better performance when high fidelity isn't required
5. Use appropriate waitUntil events based on your needs:
   • firstMeaningfulPaint (default) for general captures
   • networkIdle for dynamic content
   • load for static content
6. Set custom userAgent when needed to handle specific site requirements
7. Enable caching with appropriate TTL for frequently accessed pages
8. Use signed API keys for enhanced security in production environments

Need Help?

If you encounter any issues, have questions, or need additional features not covered here, please don't hesitate to reach out to our support team at support@scrnify.com. We're here to help!