Web Scraping API für Markdown, Screenshots und strukturierte Daten#

POST /v2/perceive ist die Web-Scraping-API von EnConvert: Sie rendert eine URL einmal in einem echten Headless-Browser (JavaScript wird ausgeführt, Lazy-Content wird geladen) und liefert aus diesem einen Render jede Ausgabe zurück, die du anforderst: sauberes Markdown (standardmäßig nur der Hauptinhalt, Site-Chrome entfernt), bereinigtes oder rohes HTML, einen Screenshot, ein PDF, das Link- und Bild-Inventar sowie strukturierte Daten (Seitenmetadaten, JSON-LD, Überschriften, Tabellen). Datei-Ausgaben kommen als kurzlebige, vorsignierte Download-URLs zurück, der strukturierte Block inline, und Batches mit mehr als 10 URLs laufen asynchron hinter einer abgefragten job_id. Eine einzige Anfrage ersetzt einen ganzen Stapel einzelner Aufrufe: url-to-markdown, url-to-screenshot, url-to-pdf, plus dein eigenes Scraping.

Hier ist der kleinste sinnvolle Aufruf. Sende eine URL und erhalte sauberes Markdown sowie die strukturierten Metadaten der Seite zurück:

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"]
  }'

Die Antwort enthält eine vorsignierte Download-URL für die Markdown-Datei sowie den strukturierten Block inline:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url": "https://example.com/pricing",
    "url_final": "https://example.com/pricing",
    "content_hash": "9f2b8c1a...d4e5",
    "render_quality": 0.93,
    "cache_hit": false,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "object_key": "env/files/4127/v2-perceive/per_3f9a..._markdown.md",
            "size_bytes": 8421,
            "content_type": "text/markdown; charset=utf-8",
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {
            "title": "Pricing",
            "description": "Simple, usage-based pricing."
        },
        "structured_data": [
            {"@type": "Product", "name": "Studio", "offers": {"price": "99"}}
        ]
    },
    "extraction_tier": "heuristic",
    "tokens": {"input": 0, "output": 0},
    "cost_cents": 0.0,
    "duration_ms": 6230,
    "warnings": []
}

Endpunkte#

Content-Type: application/json bei jedem POST.

Authentifizierung#

Authentifiziere dich mit einem privaten Schlüssel im X-API-Key-Header für Server-zu-Server-Aufrufe. Diesen Weg verwenden die folgenden Beispiele.

X-API-Key: sk_your_private_key

Öffentliche Schlüssel mit einem JWT-Bearer-Token funktionieren ebenfalls, nach demselben Ablauf wie bei jedem anderen Endpunkt: Erzeuge ein Token mit deinem pk_-Schlüssel und sende es dann als Authorization: Bearer <token>. Den vollständigen Ablauf, einschließlich Domain-Lock und Token-Refresh, findest du im Authentifizierungsleitfaden.

Jeder API-Schlüssel hat eine Allowlist erlaubter Endpunkte. Steht /v2/perceive nicht auf der Liste des Schlüssels, wird die Anfrage mit 403 abgelehnt.

Wie perceive funktioniert#

Eine Anfrage löst einen Browser-Render über ein gemeinsam genutztes Headless-Chrome-Singleton aus und materialisiert anschließend jede Ausgabe aus diesem Render. Du bezahlst innerhalb eines einzelnen Aufrufs nie zweimal für dieselbe Seite.

1. Render. Die Seite wird über einen automatischen Multi-Engine-Fallback abgerufen: zuerst ein schneller Echt-Browser-TLS-Fingerprint, mit Eskalation zu Headless-Chrome, wenn die Seite blockiert ist oder JavaScript benötigt, und noch einmal zu einem Stealth-gehärteten Render, wenn eine Seite weiterhin durch Anti-Bot-Schutz blockiert wirkt, sodass mehr reale Seiten mit nutzbarem Inhalt zurückkommen. Im Browser werden Cookie-Banner geschlossen, die Seite wird gescrollt, um Lazy-Loaded-Content auszulösen, Sticky-Header werden behandelt, und Bilder erhalten Zeit zum Laden. Es ist dieselbe Capture-Pipeline, die auch den url-to-pdf-Endpunkt antreibt.
2. Materialisieren. Aus dem gerenderten DOM erstellt perceive alles, was du in outputs angegeben hast: Markdown, bereinigtes/rohes HTML, Links, Bilder, einen Screenshot, ein PDF. Das DOM wird zuvor normalisiert, damit das Markdown widerspiegelt, was ein Leser sieht: Code-Fences behalten ihre Sprache, Card-Links ihre Struktur, und Interface-Elemente werden unter only_main_content entfernt. Siehe Markdown-Qualität.
3. Extrahieren. Wenn du die Ausgabe structured angefordert hast, führt perceive einen heuristischen Durchlauf für Seitenmetadaten, JSON-LD, Überschriften und Tabellen aus. Wenn du zusätzlich ein schema sendest und dein Plan die LLM-Stufe enthält, füllt ein LLM-gestütztes Modell das Schema, wenn der heuristische Durchlauf nicht ausreicht.
4. Bewerten. Ein Render-Qualitäts-Score (0.0–1.0) unterscheidet einen echten Render von einem fehlgeschlagenen. Werte unter 0.40 bedeuten einen fehlgeschlagenen Render: eine Anti-Bot-Seite, eine Login-Wall, eine HTTP-Fehlerseite, ein Soft-404 oder eine leere Hülle. Sieh in deductions nach dem Grund und in status_code nach dem Upstream-Status.

Binäre und Text-Ausgaben (Markdown, HTML, Screenshots, PDFs, das Link- und Bild-JSON) werden in den Storage hochgeladen und als vorsignierte URLs zurückgegeben, die nach 15 Minuten ablaufen. Der structured-Block wird inline im JSON zurückgegeben. Rufe eine Operation mit GET /v2/perceive/{operation_id} erneut ab, um einen neuen Satz signierter URLs zu erhalten.

Request-Parameter#

Die Validierung ist strikt: Ein Request-Key, den das Schema nicht kennt, wird mit 422 abgelehnt, wobei das betroffene Feld benannt wird. Unbekannte Keys werden nie still ignoriert. Jeder 422-Body enthält außerdem ein Top-Level-Array errors mit menschenlesbaren Meldungen neben der maschinenlesbaren detail-Liste.

Kern#

Ausgaben#

outputs akzeptiert jede Kombination dieser Namen:

Markdown-Qualität#

Bevor die Seite konvertiert wird, wird das gerenderte DOM normalisiert, damit das Markdown widerspiegelt, was ein Leser sieht, und nicht, wie die Seite gebaut wurde. Das läuft bei jedem Render, sodass das Ergebnis nicht davon abhängt, welche Extraktionsstrategie für eine Seite gewinnt.

Immer angewendet, in beiden only_main_content-Modi:

• Code-Fences behalten ihre Sprache. Die Sprache wird aus der jeweils vom Site verwendeten Konvention gelesen (class="language-python", data-lang, ein blankes language-Attribut oder ein Highlighter-Wrapper) und normalisiert, sodass ```python ankommt statt eines nackten Fence.
• Card-Links bleiben lesbar. Ein Link, der eine Überschrift und eine Beschreibung umschließt, wird zu einem verlinkten Titel gefolgt von seiner Beschreibung, statt zu einem zusammengelaufenen Link wie [DatabaseSupabase provides a full Postgres database...]. Die Ziel-URL bleibt erhalten.
• Überschriften bleiben auf einer Zeile. Eine Überschrift, deren Text in einem verschachtelten Element sitzt, erzeugt kein nacktes ## mehr, unter dem der Text gestrandet ist.
• Benachbarte Elemente laufen nicht mehr zusammen. Layouts, die ihre Elemente per CSS statt per Leerraum trennen, erzeugten YesNo und EvaluationDeploymentProduction; diese lesen sich jetzt als getrennte Wörter.
• Unsichtbare Zeichen werden entfernt: Zero-Width-Spaces als Anker-Labels, weiche Trennstriche und Private-Use-Area-Glyphen aus Icon-Fonts, die als nicht darstellbare Token ankommen.
• Leere Elemente werden verworfen: reine Icon-<i>-Elemente, die als verirrte __ gerendert wurden, und Links ohne Label.

Zusätzlich mit only_main_content: true:

• Interface-Steuerelemente werden entfernt: Buttons, Tab-Leisten, Tastenkürzel-Hinweise, „Copy page“-/„On this page“-Aktionen und „War diese Seite hilfreich? Ja/Nein“-Bewertungs-Widgets. Ein Steuerelement mit echtem Inhalt (eine FAQ-Frage, ein klickbarer Card-Body) bleibt erhalten.
• Nur für Screenreader bestimmter Text wird entfernt: Skip-Links und die „Section titled ...“-Labels, die viele Doku-Themes an jede Überschrift hängen.
• Von der Site deklarierter Nicht-Inhalt wird respektiert: Blöcke mit data-nosnippet, data-pagefind-ignore oder data-noindex, sofern sie keine Überschriften oder Code enthalten.
• Doppelte Blöcke werden zusammengefasst: responsive Designs, die eine Desktop- und eine Mobile-Kopie derselben Leiste ausliefern, und Karussells, die jedes Frame vorrendern, erscheinen einmal.
• Breadcrumbs und Eyebrow-Labels über dem Seitentitel entfallen.

Aufgeschobener Inhalt bleibt bewusst erhalten: ein inaktives Tab-Panel innerhalb der Inhaltsregion enthält ein echtes Code-Beispiel (das Python-Beispiel in einem Tab, das JavaScript-Beispiel in einem anderen), sodass beide ins Markdown gelangen und nicht nur der Tab, der zum Render-Zeitpunkt zufällig ausgewählt war.

Rendering und Warten#

Authentifizierte und benutzerdefinierte Anfragen#

Strukturierte Extraktion#

Wenn structured in outputs enthalten ist, bestimmt die extract-Liste, welche Felder perceive abruft. Forderst du nichts an, greift der Standard metadata und structured_data.

Um ehrlich zu sein: prices, contacts und technologies sind reservierte Namen. Forderst du heute eines davon an, gibt es keinen Fehler: Der Name landet im warnings-Array und wird aus structured entfernt.

Schema-gesteuerte Extraktion#

Sende ein schema, um bestimmte Felder in structured.extracted abzurufen:

{
    "url": "https://example.com/product/widget",
    "outputs": ["markdown", "structured"],
    "schema": {
        "type": "object",
        "properties": {
            "name": {"type": "string"},
            "price": {"type": "number"},
            "in_stock": {"type": "boolean"}
        }
    }
}

Die LLM-gestützte Extraktionsstufe füllt das Schema, und sie greift nur, wenn alle diese Bedingungen zutreffen: du hast ein schema gesendet, dein Plan enthält die LLM-Stufe (Indie und höher), die Seite wurde nicht als blockiert bewertet, und der heuristische Durchlauf hat die Schemafelder leer gelassen. Läuft sie, ist extraction_tier gleich "llm", und tokens sowie cost_cents geben an, was diese Extraktion gekostet hat; andernfalls ist extraction_tier gleich "heuristic" und beide sind null.

Hinweis. Die Schema-Extraktion ist hart gedeckelt, um deine Rechnung zu schützen: Eine einzelne Extraktion ist pro Anfrage begrenzt, und die Projektausgaben schöpfen aus deinem monatlichen AI-Credit-Guthaben ($5 / $15 / $40 pro Monat auf Indie / Studio / Production; ungenutzte Credits werden übertragen). LLM-Extraktion verbraucht Credits, keine Ops. Wird eine Obergrenze erreicht, liefert perceive das heuristische Ergebnis mit einem Hinweis in warnings, statt zu überziehen. Auf einem Plan ohne die LLM-Stufe erhältst du nur heuristische structured-Daten.

Antwort#

Sowohl POST /v2/perceive als auch GET /v2/perceive/{operation_id} liefern dasselbe Objekt zurück.

Eine Operation abrufen#

Signierte URLs laufen nach 15 Minuten ab. Um eine Ausgabe später herunterzuladen, rufe die Operation erneut ab. Perceive signiert jede URL anhand der gespeicherten Object-Keys neu. Es findet kein erneuter Render statt, daher werden dabei keine Ops verbraucht.

curl https://api.enconvert.com/v2/perceive/per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7 \
  -H "X-API-Key: sk_your_private_key"

Eine unbekannte Operation-ID oder eine, die zu einem anderen Projekt gehört, liefert 404. Die Existenz wird projektübergreifend nie preisgegeben.

Direct Download#

Standardmäßig kommt jede Datei-Ausgabe als vorsignierte URL zurück, die du in einer zweiten Anfrage abrufst. Setze direct_download: true im POST, um den Envelope zu überspringen: Der HTTP-Response-Body ist dann die Artefakt-Bytes, ohne JSON, ohne signierte URL und ohne zweiten Abruf. Die Anfrage muss genau eine Artefakt-erzeugende Ausgabe produzieren (outputs: ["markdown"], outputs: ["pdf"], …), sonst wird sie mit 400 abgelehnt. Die Metadaten, die sonst im JSON stünden, reisen stattdessen in Response-Headern mit: Content-Disposition, X-Operation-Id, X-Object-Key, X-Cache-Hit, X-Render-Quality, X-Source-Status-Code, X-Content-Hash und X-Warnings-Count.

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"],
    "direct_download": true
  }' \
  -o post.md

Die GET-Endpunkte streamen gespeicherte Artefakte auf dieselbe Weise:

• GET /v2/perceive/{operation_id}?direct_download=true&output=markdown streamt ein Artefakt einer vergangenen Operation. output ist erforderlich, wenn die Operation mehr als ein Artefakt erzeugt hat. Ein Artefakt außerhalb des Aufbewahrungsfensters deines Plans antwortet mit 410.
• GET /v2/perceive/batch/{job_id}?direct_download=true streamt die Batch-ZIP-Datei. Das gilt für Batches mit output_mode: "zip", deren Archiv bereit ist, andernfalls kommt 400 zurück.

direct_download gilt nur für einzelne URLs: POST /v2/perceive/batch lehnt es mit 422 ab. Setze output_mode auf "zip" und lade das Archiv herunter. Siehe Batch-Perceive.

Batch-Perceive#

POST /v2/perceive/batch erfasst eine Liste von URLs, die sich einen options-Block teilen. Jede URL wird über dieselbe Pipeline wie bei einem Einzelaufruf gerendert und erzeugt ihre eigene Operationszeile.

curl -X POST https://api.enconvert.com/v2/perceive/batch \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      "https://example.com/a",
      "https://example.com/b",
      "https://example.com/c"
    ],
    "options": {"outputs": ["markdown"]},
    "output_mode": "manifest"
  }'

Batches mit 10 oder weniger URLs laufen inline und antworten mit 200, wobei jedes Ergebnis befüllt ist. Größere Batches antworten mit 202 und einer job_id; die URLs werden nacheinander abgearbeitet, und du fragst die Ergebnisse ab:

curl https://api.enconvert.com/v2/perceive/batch/{job_id} \
  -H "X-API-Key: sk_your_private_key"

Die Batch-Antwort meldet den aggregierten Fortschritt und enthält pro URL ein vollständiges perceive-Ergebnis, sobald gerendert wurde:

{
    "job_id": "bat_8c1a...",
    "status": "partial",
    "output_mode": "manifest",
    "total": 3,
    "completed": 2,
    "failed": 1,
    "pending": 0,
    "items": [
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/a"},
        {"operation_id": "per_...", "status": "completed", "url": "https://example.com/b"},
        {"operation_id": "per_...", "status": "failed", "url": "https://example.com/c"}
    ]
}

status ist queued, processing, completed, failed, partial (manche URLs erfolgreich, manche fehlgeschlagen) oder canceled. Setze output_mode auf zip, um jedes Artefakt in einer einzigen ZIP-Datei zu bündeln, die nach Abschluss des Batches im Feld zip zurückgegeben wird.

Dauerhaft und wiederaufnehmbar#

Batches sind restart-sicher. Wenn der Dienst neu startet, während ein Batch läuft, wird der Batch automatisch fortgesetzt und rendert nur die URLs erneut, die noch nicht fertig waren, sodass bereits abgeschlossene URLs ihre Artefakte behalten. Du musst einen Batch wegen eines Neustarts nie erneut einreichen.

Einen Batch abbrechen#

DELETE /v2/perceive/batch/{job_id} bricht einen laufenden Batch ab. Der Worker stoppt zwischen den URLs, sodass bereits gerenderte URLs ihre Ergebnisse behalten und der Rest nicht gestartet wird. Der Aufruf ist idempotent: Das Abbrechen eines bereits abgeschlossenen Batches liefert einfach seinen aktuellen Zustand zurück, und der status des Batches wird zu canceled.

curl -X DELETE https://api.enconvert.com/v2/perceive/batch/{job_id} \
  -H "X-API-Key: sk_your_private_key"

Caching#

cache_mode steuert, wie perceive seinen 1-Stunden-Ergebnis-Cache behandelt, der nach deinem Projekt, der URL und den render-relevanten Request-Optionen geschlüsselt ist.

Wichtig: Ein Cache-Hit berechnet trotzdem eine Op gegen dein monatliches Ops-Kontingent. Das Kontingent misst Operationen, nicht Browser-Renders, daher spart dir der Cache Renderzeit, keine Ops.

Codebeispiele#

curl: Nur Markdown#

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/blog/post",
    "outputs": ["markdown"]
  }'

curl: Markdown plus strukturierte Daten#

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/pricing",
    "outputs": ["markdown", "structured"],
    "extract": ["metadata", "structured_data", "tables"]
  }'

curl: Alle Ausgaben plus PDF#

curl -X POST https://api.enconvert.com/v2/perceive \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/report",
    "outputs": ["markdown", "html_cleaned", "screenshot_full_page", "pdf"],
    "pdf_options": {"format": "A4", "print_background": true}
  }'

Python#

import requests

response = requests.post(
    "https://api.enconvert.com/v2/perceive",
    headers={"X-API-Key": "sk_your_private_key"},
    json={
        "url": "https://example.com/pricing",
        "outputs": ["markdown", "structured"],
        "extract": ["metadata", "tables"],
    },
)
response.raise_for_status()
data = response.json()

# Download the Markdown artifact from its signed URL
markdown_url = data["outputs"]["markdown"]["url"]
markdown_text = requests.get(markdown_url).text

print(data["structured"])
print(markdown_text)

Node.js#

const res = await fetch("https://api.enconvert.com/v2/perceive", {
    method: "POST",
    headers: {
        "Content-Type": "application/json",
        "X-API-Key": "sk_your_private_key"
    },
    body: JSON.stringify({
        url: "https://example.com/pricing",
        outputs: ["markdown", "structured"],
        extract: ["metadata", "tables"]
    })
});

const data = await res.json();

// Download the Markdown artifact from its signed URL
const markdownText = await fetch(data.outputs.markdown.url).then(r => r.text());

console.log(data.structured);
console.log(markdownText);

Wenn du EnConvert aus Claude, Cursor oder einem anderen MCP-Client aufrufst, ist dieselbe Funktion als perceive_url-Tool verfügbar. Siehe die MCP-Serverseite.

Fehlerantworten#

Unbekannte Request-Keys werden mit einem 422 abgelehnt, das das Feld benennt, und zwar auf /v2/perceive, /v2/perceive/batch, /v2/discover und /v2/lookup gleichermaßen. Still ignoriert werden sie nie. Jeder 422-Body enthält ein Top-Level-Array errors mit menschenlesbaren Meldungen neben der rohen detail-Liste.

Die vollständige Statuscode-Referenz findest du im Fehlercode-Leitfaden.

Limits#

Häufig gestellte Fragen#

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

Sende POST /v2/perceive mit {"url": "...", "outputs": ["markdown"]}. Die Seite wird in Headless-Chrome gerendert, und die Antwort enthält eine vorsignierte Download-URL für die Markdown-Datei. Standardmäßig entfernt only_main_content das Site-Chrome, sodass du den Artikel bekommst, nicht die Navigation; setze "only_main_content": false für die vollständige Seite, oder füge "direct_download": true hinzu, um die Markdown-Bytes direkt im Response-Body zu erhalten.

Kann ich einen Screenshot und Markdown aus demselben Render erhalten?#

Ja. outputs akzeptiert jede Kombination, also erzeugt ["markdown", "screenshot"] (oder screenshot_full_page für die gesamte Scroll-Höhe) beides aus einem einzigen Browser-Render. Du bezahlst innerhalb eines Aufrufs nie zweimal für dieselbe Seite.

Rendert /v2/perceive JavaScript-Seiten?#

Ja. Jede Anfrage führt einen echten Headless-Chrome-Render aus: Cookie-Banner werden geschlossen, die Seite wird gescrollt, um Lazy-Loaded-Content auszulösen, und du kannst die Seite vor der Erfassung mit wait_for (einem CSS-Selektor oder JS-Ausdruck), js_code und block_resources steuern.

Warum funktioniert meine signierte Download-URL nicht mehr?#

Signierte URLs laufen nach 15 Minuten ab (expires_in: 900). Rufe die Operation mit GET /v2/perceive/{operation_id} erneut ab, um frisch signierte URLs zu erhalten. Es findet kein erneuter Render statt, und es werden keine Ops verbraucht.

Zählt ein zwischengespeichertes Ergebnis trotzdem gegen mein Kontingent?#

Ja. Ein Cache-Hit berechnet eine Op, denn das monatliche Kontingent misst Operationen, nicht Browser-Renders. Setze cache_mode auf bypass, um den 1-Stunden-Cache zu überspringen, oder auf refresh, um neu zu rendern und den zwischengespeicherten Eintrag zu ersetzen.