API zur Konvertierung von Webseiten#
Die Webseiten-Endpunkte rendern Live-URLs in einem echten Browser und konvertieren sie in PDFs, Ganzseiten-PNG-Screenshots oder sauberes GitHub-Flavored Markdown. Einzel-URL-Endpunkte laufen synchron (oder asynchron im Batch), während die Website-Endpunkte eine gesamte Website per Sitemap-Parsing oder vollständigem Breadth-First-Crawl durchlaufen und jede Seite in einem ZIP-Archiv bündeln. Alle Endpunkte teilen sich dieselbe Browser-Pipeline: Cookie-Banner-Ablehnung, Lazy-Load-Scrolling, Sticky-Header-Behandlung sowie Unterstützung für Seiten hinter HTTP Basic Auth, injizierten Cookies oder benutzerdefinierten Headern.
Unterstützte Konvertierungen#
| Konvertierung | Endpunkt | Beschreibung |
|---|---|---|
| URL zu PDF | POST /v1/convert/url-to-pdf |
Konvertiert jede öffentlich zugängliche URL in ein hochwertiges PDF, mit fortlaufender Einzelseiten- oder paginierter Ausgabe, benutzerdefinierten Seitengrößen, Kopf-/Fußzeilen und asynchronem Batch-Modus. |
| URL zu Screenshot | POST /v1/convert/url-to-screenshot |
Erstellt einen Ganzseiten-Screenshot jeder URL als hochwertiges PNG und passt den Viewport an die tatsächliche Inhaltshöhe an, sodass die gesamte Seite in einem Bild enthalten ist. |
| URL zu Markdown | POST /v1/convert/url-to-markdown |
Konvertiert eine Webseite in sauberes GitHub-Flavored Markdown mit YAML-Frontmatter, wobei Readability-Extraktion überflüssigen Boilerplate-Code entfernt. Entwickelt für LLM- und RAG-Ingestion-Pipelines. |
| Website zu PDF | POST /v1/convert/website-to-pdf |
Durchsucht eine gesamte Website per Sitemap oder vollständigem Breadth-First-Crawl, konvertiert jede gefundene Seite in ein PDF und bündelt die Ergebnisse in einem einzigen ZIP-Archiv. |
| Website zu Screenshot | POST /v1/convert/website-to-screenshot |
Ermittelt jede Seite einer Website per Sitemap oder vollständigem Crawl und erstellt für jede einen Ganzseiten-Screenshot als PNG, ausgeliefert als ein ZIP-Archiv. |
Gemeinsame Konventionen#
- Authentifizierung: Jeder Endpunkt akzeptiert einen privaten Schlüssel im
X-API-Key-Header; die drei Einzel-URL-Endpunkte akzeptieren außerdem JWT-Bearer-Token auf Basis eines öffentlichen Schlüssels (beschränkt auf eine einzelne URL, den synchronen Modus und Direct Download), während die Website-Endpunkte einen privaten Schlüssel erfordern. Siehe Authentifizierung. - Sync vs. async: Einzel-URL-Endpunkte laufen standardmäßig synchron und wechseln bei Batches in den asynchronen Modus (
async_mode=true, HTTP 202 mit einerbatch_id); die Website-Endpunkte sind immer asynchron. FrageGET /v1/convert/batch/{batch_id}für die Ergebnisse ab. Siehe Synchrone und asynchrone Jobs. - Antworten: Abgeschlossene Konvertierungen liefern eine presigned Download-URL und einen
object_key; Einzel-URL-Endpunkte können mitdirect_download=truestattdessen die rohen Ausgabe-Bytes zurückgeben. - Browser- und Rendering-Parameter:
viewport_width/viewport_height,handle_cookies,enable_scroll,load_media,wait_for_imagesundhandle_sticky_headergelten für alle fünf Endpunkte, ebenso wie die Optionenauth,cookies(max. 50) undheaders(max. 20) für geschützte Seiten. Siehe Synchrone und asynchrone Jobs. - Fehler und Plan-Beschränkungen: Alle Endpunkte verwenden dieselben Statuscodes:
400für ungültige Eingaben,401für falsche Zugangsdaten,402für Kontingent- oder Speicherlimits und403für plan-abhängige Funktionen (async, Webhooks, ZIP-Ausgabe, Basic Auth, Website-Erfassung). Siehe Fehlercodes.
Häufig gestellte Fragen#
Welchen Endpunkt sollte ich für eine einzelne Seite gegenüber einer gesamten Website verwenden?#
Verwende url-to-pdf, url-to-screenshot oder url-to-markdown für eine URL oder eine explizite Liste von URLs. Verwende website-to-pdf oder website-to-screenshot, wenn die API die Seiten selbst über sitemap.xml-Parsing oder einen vollständigen Breadth-First-Crawl ermitteln und alles als ein ZIP zurückgeben soll.
Können diese Endpunkte Seiten hinter einem Login konvertieren?#
Ja, auf Plänen mit Basic-Auth-Zugriff. Alle fünf Endpunkte akzeptieren ein auth-Objekt für HTTP Basic Auth, bis zu 50 injizierte cookies für sitzungsbasierten Zugriff und bis zu 20 benutzerdefinierte headers. Diese Optionen sind nützlich für Staging-Sites, mitgliederbeschränkte Seiten und Dashboards.
Wie erhalte ich das Ergebnis eines asynchronen Jobs?#
Asynchrone Jobs liefern sofort HTTP 202 mit einer batch_id. Frage GET /v1/convert/batch/{batch_id} mit deinem privaten Schlüssel ab, um URL-bezogene Status und presigned Download-URLs zu erhalten, gib eine callback_url an, um bei Abschluss einen Webhook-POST zu erhalten, oder verlasse dich auf die Abschluss-E-Mail, die an notification_email gesendet wird (standardmäßig der Projektinhaber).