Website-Screenshot-API#

Der Endpunkt POST /v1/convert/url-to-screenshot erfasst einen Ganzseiten-Screenshot einer beliebigen öffentlich zugänglichen URL als hochwertiges PNG-Bild. Er behandelt automatisch Cookie-Banner, Modals, Lazy-Loading-Inhalte, scroll-getriggerte Animationen und Sticky-Header, um eine saubere, präzise Erfassung zu erzeugen. Führe ihn synchron aus, um eine presigned Download-URL oder rohe PNG-Bytes zu erhalten, oder nutze den asynchronen Modus, um mehrere URLs in einem Batch als Screenshot zu erfassen.

Endpunkt#

POST /v1/convert/url-to-screenshot

Content-Type: application/json

Ausgabeformat: PNG (immer). Das Ausgabeformat ist nicht konfigurierbar. Alle Screenshots werden als ganzseitige PNG-Bilder erfasst.

Authentifizierung#

Dieser Endpunkt unterstützt sowohl die Authentifizierung mit privatem als auch mit öffentlichem Schlüssel.

Privater Schlüssel#

Übergib deinen geheimen Schlüssel im X-API-Key-Header. Nutze dies für Server-zu-Server-Aufrufe, bei denen der Schlüssel niemals gegenüber dem Client offengelegt wird.

X-API-Key: sk_your_private_key

Öffentlicher Schlüssel mit JWT#

Erzeuge für die clientseitige Nutzung zunächst mit deinem öffentlichen Schlüssel ein JWT-Token und übergib es anschließend als Bearer-Token.

Schritt 1 -- Token abrufen:

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

Schritt 2 -- Token verwenden:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

Anfrageparameter#

Top-Level-Parameter#

Browser- und Rendering-Parameter#

Authentifizierung & benutzerdefinierte Anfragen#

Cookie-Objekt-Schema#

Jeder Eintrag im Array cookies muss folgender Struktur entsprechen:

Antwort#

Synchron mit direktem Download (direct_download=true)#

Privater Schlüssel -- liefert rohe PNG-Bytes zurück:

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)

Öffentlicher Schlüssel -- liefert JSON mit einer presigned URL zurück:

{
    "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"
}

Synchron ohne direkten Download (direct_download=false)#

Nur mit privaten Schlüsseln verfügbar.

{
    "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
}

Asynchroner Modus#

Liefert sofort eine batch_id zur Nachverfolgung zurück.

HTTP 202 Accepted

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

Bei output_format=true (ZIP-Bündelung):

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

Job-Status-Abfrage (nur öffentliche Schlüssel)#

Für die Timeout-Wiederherstellung bei öffentlichen Schlüsseln:

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

Batch-Status-Abfrage (nur private Schlüssel)#

Frage bei asynchronen Batch-Jobs mit der batch_id aus der 202-Antwort ab:

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

Liefert den Gesamtstatus, Status pro URL sowie presigned Download-URLs zurück. Das vollständige Antwortschema findest du unter Batch-Status-Abfrage.

Webhook-Callback-Payload#

Wenn eine callback_url angegeben ist, sendet EnConvert nach Abschluss eine POST-Anfrage an diese URL.

Einzelner 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}
    ]
}

Funktionen#

Ganzseitige Erfassung#

Jeder Screenshot erfasst den gesamten Seiteninhalt, nicht nur den sichtbaren Viewport. Der Converter:

1. Rendert die Seite mit der angegebenen viewport_width und viewport_height
2. Scrollt durch die Seite, um sämtliche Lazy-Loading-Inhalte auszulösen
3. Berechnet die tatsächliche Inhaltshöhe mithilfe eines DOM-Tree-Walkers, der die maximale untere Position aller sichtbaren Elemente misst
4. Passt den Viewport an, sodass er die vollständige Inhaltshöhe umfasst
5. Erfasst den Screenshot mit full_page=true

Das Ergebnis ist ein einzelnes, hohes PNG-Bild der kompletten Seite.

Klarer Erfassungsmodus#

EnConvert behandelt automatisch gängige Hindernisse auf Webseiten, um saubere Screenshots zu erzeugen:

• Cookie-Consent-Banner -- Schließt automatisch Banner von OneTrust, Cookiebot, Didomi, Usercentrics und generischen Implementierungen. Funktioniert sowohl auf der Hauptseite als auch in iframes.
• Schließen von Modals und Popups -- Schließt Overlays mit mehreren Strategien: Escape-Taste, ARIA-Schließen-Buttons, klassenbasierte Schließen-Buttons ("Close", "Not now", "No thanks", "Skip") und rollenbasierte Dialog-Buttons. Entfernt nach dem Schließen verbleibende Blur-, Backdrop- und Inert-Effekte.
• Aufdecken von Scroll-Animationen -- Erzwingt die Sichtbarkeit von Elementen, die durch scroll-getriggerte Animationsbibliotheken wie WOW.js, AOS, ScrollReveal, GSAP ScrollTrigger sowie generische Animationsklassen (.fadeIn, .slideIn usw.) verborgen werden. Deckt außerdem alle Swiper-Slides auf.
• Dropdown-Bereinigung -- Schließt alle geöffneten Dropdowns, wandelt Navigations-Button-Elemente in echte Anchor-Links um, damit sie visuell sauber bleiben, blendet role="menu"-Elemente aus und positioniert fixierte Header auf statische Positionierung um.

Normalisierung von Viewport-Einheiten#

Screenshots erfordern eine besondere Behandlung von CSS-Viewport-Einheiten (vh, svh, lvh, dvh), da der Viewport auf die volle Seitenhöhe angepasst wird. Ohne Normalisierung würden mit Viewport-Einheiten dimensionierte Elemente auf enorme Größen anwachsen. Der Converter:

• Wandelt alle viewport-relativen Einheiten anhand der ursprünglichen Viewport-Höhe in feste Pixelwerte um
• Begrenzt ungewöhnlich hohe Bilder und Videos auf das 1,5-fache der ursprünglichen Viewport-Höhe
• Behandelt Elementor-spezifische Eigenheiten bei der Höhe (Flex-Container, Motion-Effekte, Hintergrund-Container)
• Erhält die Videodimensionen während des gesamten Normalisierungsprozesses

HTTP Basic Auth#

Übergib auth mit username und password, um Seiten hinter HTTP Basic Authentication zu erfassen.

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

Cookie-Injection#

Schleuse bis zu 50 Cookies ein, bevor die Seite lädt. Nützlich, um Seiten zu erfassen, die eine aktive Sitzung erfordern.

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

Benutzerdefinierte Header#

Sende bis zu 20 benutzerdefinierte HTTP-Header mit jeder Anfrage an die Zielseite.

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

Lazy-Loading von Bildern#

Wenn load_media und enable_scroll aktiviert sind (beide standardmäßig true), scrollt der Converter die Seite langsam (120px alle 90ms), um Lazy-Loader auszulösen, und wartet anschließend mit einer 500ms langen Layout-Stabilisierungsphase, bis alle Bilder vollständig geladen sind.

Setze load_media=false für eine schnellere Erfassung. Der Converter nutzt dann schnelles Scrollen (300px alle 30ms) mit einer kürzeren 100ms-Stabilisierung, wobei Medien jedoch als Platzhalter erscheinen können.

Behandlung von Sticky-Headern#

Wenn aktiviert (Standard true), erkennt der Converter fixierte und sticky positionierte Elemente, die wie Header wirken, positioniert sie für einen sauberen Screenshot auf statische Positionierung um und scrollt vor der Erfassung an den Seitenanfang.

Weitere Rendering-Funktionen#

• Screen-Media-Emulation -- Die Seite wird mit dem CSS-Medientyp screen gerendert (nicht print), sodass der Screenshot dem entspricht, was Nutzer in ihrem Browser sehen.
• Stealth-Modus -- Nutzt Browser-Fingerprint-Maskierung, um Bot-Erkennung auf geschützten Seiten zu vermeiden.
• Popup-Interception -- Schließt automatisch alle neuen Browser-Tabs oder Popups, die von der Seite ausgelöst werden.
• CSP-Bypass -- Behandelt Content-Security-Policy- und Trusted-Types-Beschränkungen, die die Manipulation der Seite andernfalls blockieren würden.
• Shadow-Erhaltung -- Elemente mit box-shadow und text-shadow werden markiert, damit Schatten im Screenshot korrekt gerendert werden.

Einschränkungen nach Plan#

Asynchroner Modus#

Der asynchrone Modus ist nützlich für lang laufende Erfassungen oder wenn mehrere URLs als Screenshot erfasst werden sollen.

So funktioniert es#

1. Sende eine Anfrage mit async_mode=true (oder übergib mehrere URLs, wodurch Async automatisch aktiviert wird).
2. Die API liefert sofort HTTP 202 mit einer batch_id und url_count zurück.
3. Jede URL wird im Hintergrund erfasst, in den Storage hochgeladen und einzeln nachverfolgt.
4. Überwache den Abschluss per Batch-Status-Abfrage, E-Mail-Benachrichtigung oder Webhook-Callback.

E-Mail-Benachrichtigung#

Standardmäßig wird eine Abschluss-E-Mail an die E-Mail-Adresse des Projektinhabers gesendet. Überschreibe dies mit notification_email:

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

Webhook-Callback#

Gib eine callback_url an, um bei Abschluss automatisch eine POST-Benachrichtigung zu erhalten:

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

Batch- und Massenverarbeitung#

Erfasse mehrere URLs in einer einzigen Anfrage. Erfordert den asynchronen Modus und einen privaten Schlüssel.

Einzelne Ausgabe (Standard)#

Jede URL erzeugt eine eigene PNG-Datei:

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

ZIP-Bündel-Ausgabe#

Bündle alle Screenshots in einem einzigen ZIP-Archiv:

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

Codebeispiele#

Python (privater Schlüssel)#

import requests

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

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

PHP (privater Schlüssel)#

$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_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 (privater Schlüssel)#

const response = await fetch("https://api.enconvert.com/v1/convert/url-to-screenshot", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_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 (privater Schlüssel)#

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_your_private_key")

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

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

JavaScript -- Browser (öffentlicher Schlüssel)#

// Step 1: Get a JWT token
const tokenRes = await fetch("https://api.enconvert.com/v1/auth/token", {
    method: "POST",
    headers: { "X-API-Key": "pk_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 (öffentlicher Schlüssel)#

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

Fehlerantworten#

Limits#

Häufig gestellte Fragen#

Wie erstelle ich per API einen Ganzseiten-Screenshot einer Website?#

Sende eine POST-Anfrage an /v1/convert/url-to-screenshot mit einem JSON-Body, der url enthält, und authentifiziere dich mit deinem privaten Schlüssel im X-API-Key-Header (oder einem JWT-Bearer-Token aus einem öffentlichen Schlüssel). Jede Erfassung umfasst den gesamten Seiteninhalt, nicht nur den sichtbaren Viewport. Der Converter passt den Viewport auf die volle Inhaltshöhe an und erfasst mit full_page=true.

Kann ich das Ausgabeformat des Screenshots auf JPEG oder WebP ändern?#

Nein. Das Ausgabeformat ist nicht konfigurierbar. Alle Screenshots werden als ganzseitige PNG-Bilder erfasst.

Wie steuere ich die Breite und Größe des Screenshots?#

Setze viewport_width (Standard 1920). Die Breite des Screenshots entspricht diesem Wert. Die Höhe des Screenshots wird durch die vollständige Seiteninhaltshöhe bestimmt, wobei viewport_height (Standard 1080) als Referenz für das Rendering und die Berechnung der Viewport-Einheiten dient.

Kann ich eine Seite hinter einem Login als Screenshot erfassen?#

Ja. Verwende den Parameter auth für HTTP Basic Auth, schleuse mit cookies bis zu 50 Sitzungs-Cookies ein oder sende mit headers bis zu 20 benutzerdefinierte HTTP-Header. Diese Optionen erfordern Basic-Auth-Zugriff in deinem Plan.

Wie entfernt die API Cookie-Banner und Popups aus Screenshots?#

Mit aktiviertem handle_cookies (Standard true) schließt der Converter automatisch Consent-Banner von OneTrust, Cookiebot, Didomi, Usercentrics und generischen Implementierungen, sowohl auf der Hauptseite als auch in iframes. Modals und Popups werden über die Escape-Taste, ARIA-Schließen-Buttons, klassenbasierte Schließen-Buttons und rollenbasierte Dialog-Buttons geschlossen, wobei verbleibende Blur- und Backdrop-Effekte entfernt werden.