Website-Screenshot-API#

Der Endpunkt POST /v1/convert/website-to-screenshot ermittelt jede Seite einer Website (per Sitemap-Parsing oder einem vollständigen Breadth-First-Crawl), erstellt einen Full-Page-PNG-Screenshot jeder Seite und bündelt die Ergebnisse in einem einzigen ZIP-Archiv. Jobs laufen immer asynchron: Die API gibt sofort HTTP 202 mit einer batch_id zurück, der Abschluss wird per Batch-Status-Polling, Webhook-Callback oder E-Mail-Benachrichtigung signalisiert, und die Batch-Status-Antwort enthält eine vorsignierte Download-URL für das fertige ZIP. Erfordert einen kostenpflichtigen Plan und einen privaten API-Key.

Endpunkt#

POST /v1/convert/website-to-screenshot

Content-Type: application/json

Ausgabeformat: ZIP-Archiv mit einem PNG-Screenshot pro entdeckter Seite.

Modus: Immer asynchron. Gibt sofort HTTP 202 zurück.

Authentifizierung#

Dieser Endpunkt erfordert einen privaten API-Key. Öffentliche Keys werden für die Website-Erfassung nicht unterstützt.

X-API-Key: sk_your_private_key

Request-Parameter#

Parameter zur Website-Erkennung#

Benachrichtigungsparameter#

Browser- und Rendering-Parameter#

Diese Einstellungen gelten für die Erfassung jeder einzelnen Seite innerhalb der Website.

Authentifizierung und benutzerdefinierte Anfragen#

Crawl-Modi#

"auto" (Standard)#

Verwendet den höchsten Crawl-Modus, den Ihr Plan zulässt. Wenn Ihr Plan vollständiges Crawling unterstützt, wird ein Full-Crawl ausgeführt. Wenn Ihr Plan nur Sitemap unterstützt, wird die Sitemap-Ermittlung ausgeführt.

"sitemap"#

Ermittelt Seiten durch Parsen der sitemap.xml der Website:

1. Ruft {base_url}/sitemap.xml ab (30-Sekunden-Timeout)
2. Wenn das Root-Element <sitemapindex> ist, werden alle untergeordneten Sitemaps rekursiv abgerufen
3. Extrahiert alle <url><loc>-Einträge aus <urlset>-Elementen
4. Gibt die vollständige Liste der entdeckten URLs zurück

Gibt einen Fehler zurück, wenn die Sitemap fehlt, einen Nicht-200-Status zurückgibt, ungültiges XML enthält oder keine URLs hat.

"full"#

Führt einen umfassenden zweiphasigen Crawl durch:

Phase 1 -- Seed-Ermittlung:

1. Parst robots.txt nach Sitemap-Direktiven und Crawl-Regeln
2. Prüft Standard-Sitemap-Pfade (/sitemap.xml, /wp-sitemap.xml, /sitemap_index.xml usw.)
3. Ermittelt RSS-/Atom-Feeds aus <link>-Tags und gängigen Feed-Pfaden
4. Extrahiert Seed-URLs aus allen entdeckten Quellen

Phase 2 -- Breadth-First-Link-Crawl:

1. Startet bei der Basis-URL plus allen Seed-URLs
2. Besucht jede Seite und reiht Links derselben Domain ein
3. Wendet include_patterns und exclude_patterns an, um Links zu filtern
4. Berücksichtigt robots.txt-Regeln
5. Erkennt und vermeidet unendliche URL-Fallen (Kalenderseiten, facettierte Filter usw.)
6. Dedupliziert URLs durch Normalisierung von Schema, Host und Query-Parametern sowie Entfernen von Tracking-Parametern (utm_*, fbclid, gclid usw.)

Standard-Ausschlussmuster (wenn exclude_patterns nicht angegeben wird):

• Statische Assets: *.pdf, *.zip, *.jpg, *.png, *.gif, *.svg, *.css, *.js, *.xml, *.json, *.mp4, *.webm, *.woff, *.woff2
• Geschützte Pfade: /login, /admin, /cart, /checkout
• Tiefe Paginierung: URLs mit page=-Parametern über 3 Stellen

Antwort#

202 Accepted (sofort)#

{
    "status": "processing",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "url_count": 42,
    "total_discovered": 42,
    "discovery_method": "sitemap",
    "output_format": "zip"
}

Batch-Status-Polling#

Fragen Sie mit der batch_id aus der 202-Antwort ab:

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

Gibt den Gesamtstatus, den Status pro URL und bei Abschluss eine vorsignierte Download-URL für das ZIP zurück. Das vollständige Antwortschema finden Sie unter Batch-Status-Polling.

Webhook-Callback-Payload#

Wenn callback_url angegeben ist, sendet EnConvert bei Abschluss eine POST-Anfrage:

{
    "job_id": "batch-uuid",
    "status": "success",
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "gcs_uri": "env/files/{project_id}/url-to-screenshot/website_20260405_123456789.zip",
    "filename": "website_20260405_123456789.zip",
    "file_size": 12345678,
    "total_tasks": 42,
    "successful_tasks": 40,
    "failed_tasks": 2,
    "tasks": [
        {"url": "https://example.com/", "status": "success", "filename": "example_20260405_001.png"},
        {"url": "https://example.com/about", "status": "success", "filename": "example_20260405_002.png"},
        {"url": "https://example.com/broken", "status": "failed", "error": "Timeout"}
    ]
}

E-Mail-Benachrichtigung#

Bei Abschluss des Jobs wird eine Abschluss-E-Mail an notification_email gesendet (standardmäßig an die E-Mail-Adresse des Projektinhabers), unabhängig von Erfolg oder Fehlschlag.

Plan-Beschränkungen#

Codebeispiele#

Python (privater Key)#

import requests
import time

# Start the website capture
response = requests.post(
    "https://api.enconvert.com/v1/convert/website-to-screenshot",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "crawl_mode": "sitemap",
        "output_filename": "example-screenshots",
        "viewport_width": 1440,
        "viewport_height": 900
    }
)

data = response.json()
print(f"Batch ID: {data['batch_id']}")
print(f"Pages found: {data['url_count']}")

# Poll for completion
batch_id = data["batch_id"]
while True:
    status = requests.get(
        f"https://api.enconvert.com/v1/convert/batch/{batch_id}",
        headers={"X-API-Key": "sk_your_private_key"}
    ).json()

    print(f"Status: {status['status']} ({status['completed']}/{status['total']})")

    if status["status"] in ("completed", "partial", "failed"):
        if status.get("zip_download_url"):
            print(f"Download: {status['zip_download_url']}")
        break

    time.sleep(5)

PHP (privater Key)#

$ch = curl_init("https://api.enconvert.com/v1/convert/website-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",
        "crawl_mode" => "sitemap",
        "output_filename" => "example-screenshots",
        "viewport_width" => 1440,
        "viewport_height" => 900
    ])
]);

$response = json_decode(curl_exec($ch), true);
curl_close($ch);

echo "Batch ID: " . $response["batch_id"] . "\n";
echo "Pages found: " . $response["url_count"] . "\n";

Node.js (privater Key)#

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

const data = await response.json();
console.log(`Batch ID: ${data.batch_id}`);
console.log(`Pages found: ${data.url_count}`);

// Poll for completion
const poll = async () => {
    const status = await fetch(
        `https://api.enconvert.com/v1/convert/batch/${data.batch_id}`,
        { headers: { "X-API-Key": "sk_your_private_key" } }
    ).then(r => r.json());

    console.log(`Status: ${status.status} (${status.completed}/${status.total})`);

    if (["completed", "partial", "failed"].includes(status.status)) {
        if (status.zip_download_url) console.log(`Download: ${status.zip_download_url}`);
        return;
    }
    setTimeout(poll, 5000);
};
poll();

Go (privater Key)#

package main

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

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

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/website-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))
}

Mit Webhook-Callback#

{
    "url": "https://example.com",
    "crawl_mode": "full",
    "callback_url": "https://your-server.com/webhook/enconvert",
    "output_filename": "example-full-site-screenshots",
    "include_patterns": [".*\\/blog\\/.*", ".*\\/docs\\/.*"]
}

Mit Authentifizierung (passwortgeschützte Website)#

{
    "url": "https://staging.example.com",
    "crawl_mode": "sitemap",
    "auth": {
        "username": "admin",
        "password": "staging-password"
    },
    "cookies": [
        {"name": "session_token", "value": "abc123", "domain": "staging.example.com"}
    ]
}

Fehlerantworten#

Limits#

Häufig gestellte Fragen#

Wie screenshotte ich jede Seite einer Website mit einer API?#

Senden Sie eine POST-Anfrage an /v1/convert/website-to-screenshot mit der Basis-url der Seite und Ihrem privaten Key im X-API-Key-Header. Die API ermittelt jede Seite (Sitemap oder Full-Crawl), erstellt von jeder einen Full-Page-PNG-Screenshot, bündelt sie in einem ZIP-Archiv und gibt HTTP 202 mit einer batch_id zurück, die Sie für den Download-Link abfragen können.

Kann ich die Größe oder das Format der Screenshots steuern?#

Die Screenshot-Breite entspricht viewport_width (Standard 1920), und viewport_height wird als Rendering-Referenz verwendet. Jede Seite wird immer als einzelnes Full-Page-PNG erfasst. Die Parameter single_page und pdf_options gelten nicht für Screenshots.

Wie lade ich die Screenshots herunter, wenn der Job abgeschlossen ist?#

Fragen Sie GET /v1/convert/batch/{batch_id} mit Ihrem privaten Key ab, um den Gesamtstatus, den Status pro URL und eine vorsignierte ZIP-Download-URL zu erhalten, oder übergeben Sie eine callback_url, um bei Abschluss einen Webhook-POST zu erhalten. Zusätzlich wird eine Abschluss-E-Mail an notification_email gesendet (standardmäßig an den Projektinhaber).

Kann ich eine passwortgeschützte Website oder eine Staging-Website screenshotten?#

Ja, auf Plänen mit Basic-Auth-Zugriff: Übergeben Sie auth mit username und password für HTTP Basic Auth, die auf jede Seite angewendet wird, injizieren Sie bis zu 50 Sitzungs-cookies oder senden Sie bis zu 20 benutzerdefinierte headers.

Warum gibt der Website-to-Screenshot-Endpunkt 403 Forbidden zurück?#

Die häufigsten Ursachen: Die Website-Erfassung ist im Founding-Plan nicht verfügbar, crawl_mode: "full" erfordert Studio oder höher, die Anzahl entdeckter Seiten überschreitet das Batch-Größenlimit Ihres Plans, oder ein angefordertes Feature (Webhook, Basic Auth) ist in Ihrem Plan nicht enthalten.