url-to-screenshot

Capture a full-page screenshot of any publicly accessible URL as a high-fidelity PNG image. Automatically handles cookie banners, modals, lazy-loaded content, scroll-triggered animations, and sticky headers to produce a clean, accurate screenshot.

Endpoint

POST /v1/convert/url-to-screenshot

Content-Type: application/json

Output format: PNG (always). The output format is not configurable — all screenshots are captured as full-page PNG images.

Authentication

This endpoint supports both private and public key authentication.

Private Key

Include your secret key in the X-API-Key header. Use this for server-to-server calls where the key is never exposed to the client.

X-API-Key: sk_live_your_private_key

Public Key with JWT

For client-side usage, first generate a JWT token using your public key, then pass it as a Bearer token.

Step 1 -- Get a token:

POST /v1/auth/token
X-API-Key: pk_live_your_public_key

Step 2 -- Use the token:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Request Parameters

Top-Level Parameters

Browser & Rendering Parameters

Authentication & Custom Requests

Cookie Object Schema

Each item in the cookies array must follow this structure:

Response

Synchronous with Direct Download (direct_download=true)

Private key -- returns raw PNG bytes:

HTTP 200 OK
Content-Type: image/png
Content-Disposition: inline; filename="example_20260405_123456789.png"
X-Object-Key: env/files/{project_id}/url-to-screenshot/example_20260405_123456789.png
X-File-Size: 456789
X-Conversion-Time: 8.2
X-Filename: example_20260405_123456789.png

(binary PNG data)

Public key -- returns JSON with a presigned URL:

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-screenshot/example_20260405_123456789.png",
    "filename": "example_20260405_123456789.png",
    "file_size": 456789,
    "conversion_time_seconds": 8.2,
    "job_id": "client-provided-id"
}

Synchronous without Direct Download (direct_download=false)

Available with private keys only.

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-screenshot/example_20260405_123456789.png",
    "filename": "example_20260405_123456789.png",
    "file_size": 456789,
    "conversion_time_seconds": 8.2
}

Asynchronous Mode

Returns immediately with a batch_id for tracking.

HTTP 202 Accepted

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 5,
    "output_format": "individual"
}

When output_format=true (ZIP bundling):

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 5,
    "output_format": "zip"
}

Job Status Polling (Public Keys Only)

For public key timeout recovery:

GET /v1/convert/status/{job_id}
Authorization: Bearer <jwt_token>

Batch Status Polling (Private Keys Only)

For async batch jobs, poll with the batch_id from the 202 response:

GET /v1/convert/batch/{batch_id}
X-API-Key: sk_live_your_private_key

Returns aggregate status, per-URL statuses, and presigned download URLs. See Batch Status Polling for the full response schema.

Webhook Callback Payload

When a callback_url is provided, Enconvert sends a POST request to that URL on completion.

Single URL job:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "gcs_uri": "object_key",
    "filename": "example_20260405_123456789.png",
    "file_size": 456789
}

Batch job:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "total_tasks": 10,
    "successful_tasks": 8,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/page1", "status": "success", "filename": "page1.png"},
        {"url": "https://example.com/page2", "status": "failed", "filename": null}
    ]
}

Features

Full-Page Capture

Every screenshot captures the entire page content, not just the visible viewport. The converter:

1. Renders the page at the specified viewport_width and viewport_height
2. Scrolls through the page to trigger all lazy-loaded content
3. Calculates the true content height using a DOM tree walker that measures the maximum bottom position of all visible elements
4. Resizes the viewport to encompass the full content height
5. Captures the screenshot with full_page=true

The result is a single tall PNG image of the complete page.

Clear Capture Mode

Enconvert automatically handles common web page obstacles to produce clean screenshots:

• Cookie consent banners -- Auto-dismisses banners from OneTrust, Cookiebot, Didomi, Usercentrics, and generic implementations. Operates across the main page and iframes.
• Modal and popup dismissal -- Closes overlays using multiple strategies: Escape key, ARIA close buttons, class-based close buttons ("Close", "Not now", "No thanks", "Skip"), and role-based dialog buttons. Removes residual blur, backdrop, and inert effects after dismissal.
• Scroll animation reveal -- Forces visibility on elements hidden by scroll-triggered animation libraries including WOW.js, AOS, ScrollReveal, GSAP ScrollTrigger, and generic animation classes (.fadeIn, .slideIn, etc.). Also reveals all Swiper slides.
• Dropdown cleanup -- Closes all open dropdowns, converts navigation button elements to real anchor links so they remain visually clean, hides role="menu" elements, and repositions fixed headers to static positioning.

Viewport Unit Normalization

Screenshots require special handling of CSS viewport units (vh, svh, lvh, dvh) because the viewport is resized to the full page height. Without normalization, elements sized with viewport units would stretch to enormous sizes. The converter:

• Converts all viewport-relative units to fixed pixel values based on the original viewport height
• Caps abnormally tall images and videos to 1.5x the original viewport height
• Handles Elementor-specific height quirks (flex containers, motion effects, background containers)
• Preserves video dimensions through the normalization process

HTTP Basic Auth

Pass auth with username and password to capture pages behind HTTP Basic Authentication.

{
    "url": "https://staging.example.com/dashboard",
    "auth": {
        "username": "admin",
        "password": "secret"
    }
}

Cookie Injection

Inject up to 50 cookies before the page loads. Useful for capturing pages that require an active session.

{
    "url": "https://example.com/dashboard",
    "cookies": [
        {"name": "session_id", "value": "abc123", "domain": "example.com"},
        {"name": "locale", "value": "en-US", "domain": "example.com"}
    ]
}

Custom Headers

Send up to 20 custom HTTP headers with every request to the target page.

{
    "url": "https://example.com/report",
    "headers": {
        "X-Custom-Token": "my-token-value",
        "Accept-Language": "en-US"
    }
}

Lazy Image Loading

When load_media and enable_scroll are enabled (both default to true), the converter scrolls the page slowly (120px every 90ms) to trigger lazy loaders, then waits for all images to finish loading with a 500ms layout stabilization period.

Set load_media=false for faster capture — the converter uses fast scrolling (300px every 30ms) with a shorter 100ms stabilization, but media may appear as placeholders.

Sticky Header Handling

When enabled (default true), the converter detects fixed and sticky positioned elements that appear to be headers, repositions them to static positioning for a clean screenshot, and scrolls to the top of the page before capture.

Additional Rendering Features

• Screen media emulation -- The page is rendered using screen CSS media (not print), so the screenshot matches what users see in their browser.
• Stealth mode -- Uses browser fingerprint masking to avoid bot detection on protected pages.
• Popup interception -- Automatically closes any new browser tabs or popups triggered by the page.
• CSP bypass -- Handles Content Security Policy and Trusted Types restrictions that would otherwise block page manipulation.
• Shadow preservation -- Elements with box-shadow and text-shadow are tagged to ensure shadows render correctly in the screenshot output.

Subscription Plan Gating

Async Mode

Asynchronous mode is useful for long-running captures or when screenshotting multiple URLs.

How It Works

1. Send a request with async_mode=true (or pass multiple URLs, which enables async automatically).
2. The API returns HTTP 202 immediately with a batch_id and url_count.
3. Each URL is captured in the background, uploaded to storage, and tracked individually.
4. Monitor completion via batch status polling, email notification, or webhook callback.

Email Notification

By default, a completion email is sent to the project owner's email address. Override with notification_email:

{
    "url": ["https://example.com/page1", "https://example.com/page2"],
    "async_mode": true,
    "notification_email": "team@example.com"
}

Webhook Callback

Provide a callback_url to receive an automatic POST notification on completion:

{
    "url": ["https://example.com/page1", "https://example.com/page2"],
    "async_mode": true,
    "callback_url": "https://your-server.com/webhook/enconvert"
}

Batch and Bulk Processing

Capture multiple URLs in a single request. Requires async mode and a private key.

Individual Output (default)

Each URL produces a separate PNG file:

{
    "url": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ],
    "async_mode": true
}

ZIP Bundle Output

Bundle all screenshots into a single ZIP archive:

{
    "url": [
        "https://example.com/page1",
        "https://example.com/page2",
        "https://example.com/page3"
    ],
    "async_mode": true,
    "output_format": true,
    "output_filename": "monthly-screenshots"
}

Code Examples

Python (Private Key)

import requests

response = requests.post(
    "https://api.enconvert.com/v1/convert/url-to-screenshot",
    headers={"X-API-Key": "sk_live_your_private_key"},
    json={
        "url": "https://example.com",
        "viewport_width": 1440,
        "viewport_height": 900
    }
)

data = response.json()
print(data["presigned_url"])

PHP (Private Key)

$ch = curl_init("https://api.enconvert.com/v1/convert/url-to-screenshot");
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => [
        "Content-Type: application/json",
        "X-API-Key: sk_live_your_private_key"
    ],
    CURLOPT_POSTFIELDS => json_encode([
        "url" => "https://example.com",
        "viewport_width" => 1440,
        "viewport_height" => 900
    ])
]);

$response = curl_exec($ch);
curl_close($ch);

$data = json_decode($response, true);
echo $data["presigned_url"];

Node.js (Private Key)

const response = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_live_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com",
        viewport_width: 1440,
        viewport_height: 900
    })
});

const data = await response.json();
console.log(data.presigned_url);

Go (Private Key)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "url":             "https://example.com",
        "viewport_width":  1440,
        "viewport_height": 900,
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/url-to-screenshot", bytes.NewBuffer(body))
    req.Header.Set("Content-Type", "application/json")
    req.Header.Set("X-API-Key", "sk_live_your_private_key")

    resp, _ := http.DefaultClient.Do(req)
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}

JavaScript -- Browser (Public Key)

// Step 1: Get a JWT token
const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
    method: "POST",
    headers: { "X-API-Key": "pk_live_your_public_key" }
});
const { token } = await tokenRes.json();

// Step 2: Capture screenshot
const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({
        url: "https://example.com"
    })
});

const data = await convertRes.json();
// Display the screenshot
const img = document.createElement("img");
img.src = data.presigned_url;
document.body.appendChild(img);

React (Public Key)

import { useState } from "react";

function UrlToScreenshot() {
    const [loading, setLoading] = useState(false);
    const [imageUrl, setImageUrl] = useState(null);

    async function captureScreenshot() {
        setLoading(true);
        try {
            // Get JWT token
            const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
                method: "POST",
                headers: { "X-API-Key": "pk_live_your_public_key" }
            });
            const { token } = await tokenRes.json();

            // Capture screenshot
            const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
                method: "POST",
                headers: {
                    "Content-Type": "application/json",
                    "Authorization": `Bearer ${token}`
                },
                body: JSON.stringify({ url: "https://example.com" })
            });

            const data = await convertRes.json();
            setImageUrl(data.presigned_url);
        } finally {
            setLoading(false);
        }
    }

    return (
        <div>
            <button onClick={captureScreenshot} disabled={loading}>
                {loading ? "Capturing..." : "Take Screenshot"}
            </button>
            {imageUrl && <img src={imageUrl} alt="Screenshot" style={{ maxWidth: "100%" }} />}
        </div>
    );
}

export default UrlToScreenshot;

Error Responses

Limits