URL zu PDF API#

Der Endpunkt POST /v1/convert/url-to-pdf konvertiert jede öffentlich zugängliche URL in ein hochwertiges PDF-Dokument. Er unterstützt durchgehendes einseitiges Rendering oder paginierte Ausgabe mit benutzerdefinierten Seitengrößen, außerdem Lazy-Load-Handling, das Schließen von Cookie-Bannern, HTTP Basic Auth, Cookie-Injektion und benutzerdefinierte Header. Führen Sie Konvertierungen synchron aus, um eine signierte Download-URL oder rohe PDF-Bytes zu erhalten, oder verwenden Sie den asynchronen Modus, um mehrere URLs im Batch mit Webhook- und E-Mail-Benachrichtigungen zu konvertieren.

Endpunkt#

POST /v1/convert/url-to-pdf

Content-Type: application/json

Authentifizierung#

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

Privater Schlüssel#

Fügen Sie Ihren geheimen Schlüssel im X-API-Key-Header ein. Verwenden Sie dies für Server-zu-Server-Aufrufe, bei denen der Schlüssel dem Client nie offengelegt wird.

X-API-Key: sk_your_private_key

Öffentlicher Schlüssel mit JWT#

Generieren Sie für die clientseitige Nutzung zunächst mit Ihrem öffentlichen Schlüssel ein JWT-Token und übergeben Sie es dann 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 und benutzerdefinierte Anfragen#

PDF-Optionen#

Übergeben Sie diese innerhalb eines pdf_options-Objekts im Request-Body.

Unterstützte Seitengrößen: A0, A1, A2, A3, A4, A5, A6, B0, B1, B2, B3, B4, B5, Letter, Legal, Tabloid, Ledger

Vorlagenvariablen für Header/Footer: {{page}}, {{total_pages}}, {{date}}, {{title}}, {{url}}

Cookie-Objektschema#

Jedes Element im Array cookies muss dieser Struktur folgen:

Antwort#

Synchron mit direktem Download (direct_download=true)#

Privater Schlüssel -- gibt rohe PDF-Bytes zurück:

HTTP 200 OK
Content-Type: application/pdf
Content-Disposition: inline; filename="example_20260404_123456789.pdf"
X-Object-Key: env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf
X-File-Size: 123456
X-Conversion-Time: 12.5
X-Filename: example_20260404_123456789.pdf

(binary PDF data)

Öffentlicher Schlüssel -- gibt JSON mit einer signierten URL zurück:

{
    "presigned_url": "https://spaces.example.com/...",
    "object_key": "env/files/{project_id}/url-to-pdf/example_20260404_123456789.pdf",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 12.5,
    "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-pdf/example_20260404_123456789.pdf",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456,
    "conversion_time_seconds": 12.5
}

Asynchroner Modus#

Gibt sofort eine batch_id zum Polling 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-Polling (nur öffentliche Schlüssel)#

Der Status-Polling-Endpunkt ist für die Timeout-Wiederherstellung bei öffentlichen Schlüsseln konzipiert. Wenn eine synchrone Konvertierung länger dauert als der Timeout des Reverse-Proxys (in der Regel 60s), kann der Client das Ergebnis abrufen, indem er mit der im ursprünglichen Request angegebenen job_id pollt.

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

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

Pollen Sie bei asynchronen Batch-Jobs den Batch-Status-Endpunkt mit der im 202-Response zurückgegebenen batch_id.

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

Antwort:

{
    "batch_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "processing",
    "total": 5,
    "completed": 3,
    "failed": 1,
    "in_progress": 1,
    "output_mode": "individual",
    "zip_download_url": null,
    "items": [
        {
            "source_url": "https://example.com/page1",
            "status": "Success",
            "download_url": "https://spaces.example.com/...",
            "output_file_size": 102400,
            "duration": "2.34"
        },
        {
            "source_url": "https://example.com/page2",
            "status": "Failed",
            "download_url": null,
            "output_file_size": null,
            "duration": "0.87"
        },
        {
            "source_url": "https://example.com/page3",
            "status": "In Progress",
            "download_url": null,
            "output_file_size": null,
            "duration": null
        }
    ]
}

Batch-Statuswerte:

Wenn output_mode gleich "zip" ist, wird eine einzelne zip_download_url bereitgestellt statt einzelner download_url-Werte pro Element.

Webhook-Callback-Payload#

Wenn eine callback_url angegeben wird, sendet EnConvert bei Abschluss eine POST-Anfrage an diese URL.

Job mit einzelner URL:

{
    "job_id": "activity_id",
    "status": "success",
    "batch_id": "...",
    "gcs_uri": "object_key",
    "filename": "example_20260404_123456789.pdf",
    "file_size": 123456
}

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.pdf"},
        {"url": "https://example.com/page2", "status": "failed", "filename": null}
    ]
}

Funktionen#

Sauberer Erfassungsmodus#

EnConvert behandelt automatisch häufige Hindernisse auf Webseiten, um saubere PDFs zu erzeugen:

• Cookie-Consent-Banner -- Schließt Banner von OneTrust, Cookiebot, Didomi, Usercentrics und generischen Implementierungen automatisch. Funktioniert sowohl auf der Hauptseite als auch in iframes. Verwendet eine Strategie, die zuerst schließt und dann erst akzeptiert.
• Schließen von Modals und Popups -- Schließt Overlays mit mehreren Strategien: Escape-Taste, ARIA-Schließen-Buttons, klassenbasierte Schließen-Buttons und rollenbasierte Dialog-Buttons.
• Aufdecken von Scroll-Animationen -- Erzwingt die Sichtbarkeit von Elementen, die durch scroll-getriggerte Animationsbibliotheken wie WOW.js, AOS, ScrollReveal und GSAP ScrollTrigger verborgen werden.
• Dropdown-Bereinigung -- Schließt alle offenen Dropdowns und wandelt Navigations-Button-Elemente in echte Anker-Links um, damit sie im PDF klickbar bleiben.

Seitengröße und Abmessungen#

• Einseitiger Modus (Standard): Die gesamte Webseite wird als eine durchgehende PDF-Seite gerendert. Die Höhe wird dynamisch anhand des tatsächlichen Inhalts per DOM-Traversierung berechnet.
• Paginierter Modus (single_page=false): Die Ausgabe verwendet die konfigurierten Werte page_size, orientation und margins. Unterstützt 18 benannte Größen von A0 bis Ledger oder benutzerdefinierte Abmessungen in Millimetern.

HTTP Basic Auth#

Übergeben Sie auth mit username und password, um Seiten hinter HTTP Basic Authentication zu konvertieren. Die Anmeldedaten werden bei jeder Anfrage an die Zielseite als HTTP-Credentials gesendet.

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

Cookie-Injektion#

Injizieren Sie bis zu 50 Cookies, bevor die Seite geladen wird. Nützlich zum Konvertieren von Seiten, die eine aktive Sitzung oder bestimmte Benutzereinstellungen 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#

Senden Sie bis zu 20 benutzerdefinierte HTTP-Header bei jeder Anfrage an die Zielseite. Nützlich, um API-Tokens, benutzerdefinierte User-Agents oder andere Anfrage-Metadaten zu übergeben.

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

Verzögertes Laden von Bildern (Lazy Loading)#

Wenn load_media und enable_scroll aktiviert sind (beide standardmäßig true), geht der Converter wie folgt vor:

1. Scrollt die gesamte Seite langsam (120px alle 90ms), um auf IntersectionObserver basierende Lazy-Loader auszulösen
2. Wartet, bis alle <img>-Elemente ihr onload-Event auslösen (Timeout von 5 Sekunden pro Bild)
3. Wartet nach dem Laden aller Bilder 500ms, bis sich das Layout stabilisiert

Setzen Sie load_media=false für eine schnellere Konvertierung, wenn die originalgetreue Darstellung von Medien nicht entscheidend ist -- der Converter verwendet dann schnelles Scrollen (300px alle 30ms) und fügt Platzhalter-Styles für nicht geladene Bilder hinzu.

Behandlung von Sticky Headers#

Wenn handle_sticky_header aktiviert ist (Standard true), erkennt der Converter fixed und sticky positionierte Elemente, die wie Header aussehen (anhand semantischer Tags, ARIA-Rollen und gängiger Klassennamen-Muster), und scrollt vor der Erfassung an den Seitenanfang, damit der Header am Anfang des PDFs korrekt dargestellt wird.

Header und Footer#

Fügen Sie im paginierten Modus wiederkehrende Header und Footer mit HTML-Inhalt und Vorlagenvariablen hinzu:

{
    "url": "https://example.com/report",
    "single_page": false,
    "pdf_options": {
        "page_size": "A4",
        "header": {
            "content": "<div style='font-size:10px;text-align:center;width:100%'>Confidential Report</div>",
            "height": 15
        },
        "footer": {
            "content": "<div style='font-size:9px;text-align:center;width:100%'>Page {{page}} of {{total_pages}}</div>",
            "height": 10
        }
    }
}

Graustufen-Ausgabe#

Setzen Sie pdf_options.grayscale auf true, um das fertige PDF per Ghostscript-Nachbearbeitung in Graustufen umzuwandeln.

Weitere Rendering-Funktionen#

• Normalisierung von Viewport-Einheiten -- Wandelt die CSS-Einheiten vh, svh, lvh, dvh in feste Pixelwerte um, um Layout-Probleme beim Druck-Rendering zu vermeiden.
• Stealth-Modus -- Verwendet Browser-Fingerprint-Maskierung, um Bot-Erkennung auf geschützten Seiten zu vermeiden.
• Popup-Abfangen -- Schließt automatisch alle neuen Browser-Tabs oder Popups, die von der Seite ausgelöst werden.
• CSP-Umgehung -- Behandelt Content-Security-Policy- und Trusted-Types-Beschränkungen, die die Konvertierung sonst blockieren würden.

Abo-Plan-Einschränkungen#

Asynchroner Modus#

Der asynchrone Modus eignet sich für lang laufende Konvertierungen oder beim Konvertieren mehrerer URLs.

Funktionsweise#

1. Senden Sie eine Anfrage mit async_mode=true (oder übergeben Sie mehrere URLs, wodurch der asynchrone Modus automatisch aktiviert wird).
2. Die API gibt sofort HTTP 202 mit einer batch_id und url_count zurück.
3. Jede URL wird im Hintergrund konvertiert, in den Storage hochgeladen und einzeln nachverfolgt.
4. Überwachen Sie den Abschluss per E-Mail-Benachrichtigung oder Webhook-Callback.

E-Mail-Benachrichtigung#

Standardmäßig wird bei Abschluss des asynchronen Jobs eine E-Mail an die E-Mail-Adresse des Projektinhabers gesendet. Sie können dies mit notification_email überschreiben:

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

Webhook-Callback#

Geben Sie in der Anfrage eine callback_url an, um bei Abschluss des Jobs 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"
}

Der Webhook wird mit einem Timeout von 30 Sekunden gesendet, wobei HTTP 200, 201, 202 und 204 als erfolgreiche Zustellung gelten.

Batch- und Massenverarbeitung#

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

Einzelne Ausgabe (Standard)#

Jede URL erzeugt eine separate PDF-Datei:

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

ZIP-Bündel-Ausgabe#

Bündeln Sie alle PDFs 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-reports"
}

Die ZIP-Datei wird {output_filename}_{timestamp}.zip genannt, oder batch_{timestamp}.zip, wenn kein benutzerdefinierter Name angegeben wird.

Codebeispiele#

Python (privater Schlüssel)#

import requests

response = requests.post(
    "https://api.enconvert.com/v1/convert/url-to-pdf",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com",
        "single_page": True,
        "pdf_options": {
            "page_size": "A4",
            "margins": {"top": 15, "bottom": 15, "left": 10, "right": 10}
        }
    }
)

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

PHP (privater Schlüssel)#

$ch = curl_init("https://api.enconvert.com/v1/convert/url-to-pdf");
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",
        "single_page" => true,
        "pdf_options" => [
            "page_size" => "A4",
            "margins" => ["top" => 15, "bottom" => 15, "left" => 10, "right" => 10]
        ]
    ])
]);

$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-pdf", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com",
        single_page: true,
        pdf_options: {
            page_size: "A4",
            margins: { top: 15, bottom: 15, left: 10, right: 10 }
        }
    })
});

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

Go (privater Schlüssel)#

package main

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

func main() {
    body, _ := json.Marshal(map[string]interface{}{
        "url":         "https://example.com",
        "single_page": true,
        "pdf_options": map[string]interface{}{
            "page_size": "A4",
            "margins":   map[string]int{"top": 15, "bottom": 15, "left": 10, "right": 10},
        },
    })

    req, _ := http.NewRequest("POST", "https://api.enconvert.com/v1/convert/url-to-pdf", 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: Convert URL to PDF
const convertRes = await fetch("https://api.enconvert.com/v1/convert/url-to-pdf", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "Authorization": `Bearer ${token}`
    },
    body: JSON.stringify({
        url: "https://example.com"
    })
});

const data = await convertRes.json();
// Open the PDF in a new tab
window.open(data.presigned_url, "_blank");

React (öffentlicher Schlüssel)#

import { useState } from "react";

function UrlToPdf() {
    const [loading, setLoading] = useState(false);
    const [pdfUrl, setPdfUrl] = useState(null);

    async function convertUrl() {
        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();

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

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

    return (
        <div>
            <button onClick={convertUrl} disabled={loading}>
                {loading ? "Converting..." : "Convert to PDF"}
            </button>
            {pdfUrl && <a href={pdfUrl} target="_blank" rel="noreferrer">Download PDF</a>}
        </div>
    );
}

export default UrlToPdf;

Fehlerantworten#

Limits#

Häufig gestellte Fragen#

Wie konvertiere ich eine Webseite mit einer REST-API in PDF?#

Senden Sie eine POST-Anfrage an /v1/convert/url-to-pdf mit einem JSON-Body, der die zu konvertierende url enthält, und authentifizieren Sie sich mit Ihrem privaten Schlüssel im X-API-Key-Header (oder einem JWT-Bearer-Token eines öffentlichen Schlüssels). Die synchrone Antwort gibt eine presigned_url zum Herunterladen des PDFs zurück, oder rohe PDF-Bytes bei direct_download=true.

Kann ich mehrere URLs in einer einzigen API-Anfrage in PDF konvertieren?#

Ja. Übergeben Sie im Parameter url ein Array von URLs zusammen mit async_mode=true (ein privater Schlüssel ist erforderlich); die API gibt HTTP 202 mit einer batch_id zurück, die Sie über GET /v1/convert/batch/{batch_id} abfragen. Setzen Sie output_format=true, um alle PDFs in einem einzigen ZIP-Archiv zu bündeln.

Wie erfasse ich eine gesamte Webseite als einzelne durchgehende PDF-Seite?#

Der einseitige Modus ist der Standard (single_page=true): Die gesamte Seite wird als eine durchgehende PDF-Seite gerendert, deren Höhe anhand des tatsächlichen Inhalts berechnet wird. Setzen Sie single_page=false für paginierte Ausgabe mit page_size, orientation, margins sowie optionalen Headern und Footern über pdf_options.

Warum zeigt mein PDF Cookie-Banner oder fehlende Bilder?#

Das Schließen von Cookie-Bannern (handle_cookies) und die Behandlung von Lazy Loading (enable_scroll, load_media, wait_for_images) sind standardmäßig alle true und decken OneTrust, Cookiebot, Didomi, Usercentrics und generische Banner ab. Wenn Sie load_media=false setzen, ist die Konvertierung schneller, aber Medien können als Platzhalter erscheinen.

Kann ich eine Seite hinter einem Login in PDF konvertieren?#

Ja. Verwenden Sie den Parameter auth für HTTP Basic Auth, injizieren Sie mit cookies bis zu 50 Sitzungscookies, oder senden Sie mit headers bis zu 20 benutzerdefinierte HTTP-Header. Diese Optionen erfordern Zugriff auf Basic Auth in Ihrem Plan, und auth kann nicht mit einem benutzerdefinierten Authorization-Header kombiniert werden.