API Documentation

V2 Web-Intelligence

EnConvert V2 ist eine Web-Intelligence-Schicht, die neben der V1-Konvertierungs-API steht: sechs Endpunkte, die das Web wahrnehmen, erkunden, durchsuchen, extrahieren, einlesen und überwachen. Sie teilen sich eine Headless-Chrome-Render-Pipeline, deine bestehenden API-Schlüssel und dieselbe Allowlist erlaubter Endpunkte wie V1 — und sie werden über eigene Kontingentzähler abgerechnet, sodass ein V2-Aufruf niemals eine einzige V1-Konvertierung berührt.

Hier ist der kleinste nützliche Aufruf. Sende eine URL an /v2/perceive 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_live_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 das Markdown sowie den strukturierten Block inline:

{
    "operation_id": "per_3f9a2c1b8e7d4a6f90b1c2d3e4f5a6b7",
    "status": "completed",
    "url_final": "https://example.com/pricing",
    "render_quality": 0.93,
    "outputs": {
        "markdown": {
            "url": "https://spaces.example.com/...signed...",
            "size_bytes": 8421,
            "expires_in": 900
        }
    },
    "structured": {
        "metadata": {"title": "Pricing"}
    }
}

Das ist die Form, die jeder V2-Endpunkt teilt: Sende JSON und erhalte ein Ergebnis inline oder eine kurzlebige signierte URL zu einem Artefakt zurück. Die sechs Endpunkte unterscheiden sich darin, was sie mit dem Render machen, nicht darin, wie du sie erreichst.

Die sechs Endpunkte

Jeder Endpunkt fasst einen Stapel separater Werkzeuge zu einem einzigen Aufruf gegen api.enconvert.com zusammen.

Endpunkt Funktion Ersetzt
/v2/perceive Rendert eine URL einmal und gibt jede angeforderte Ausgabe zurück — Markdown, bereinigtes/rohes HTML, Screenshot, PDF, Link- und Bildinventar, strukturierte Daten. url-to-markdown + url-to-screenshot + url-to-pdf + dein eigener Scraper
/v2/discover Bildet die URLs einer Website ausschließlich per HTTP ab — Sitemap-Parsing plus Crawl, kein Browser, kein gespeichertes Artefakt. ein Sitemap-Fetcher + ein Crawler + Dedup-/Filter-Glue
/v2/lookup Führt eine anbieterneutrale Websuche aus (sechs Kategorien) und rendert optional die Top-N-Treffer in einem Hin und Her. eine Such-API + Ergebnis-Parsing + ein Fan-out-Scraper
/v2/distill Extrahiert strukturierte Daten aus einer URL-Liste passend zu einem von dir bereitgestellten Schema — ein kostenloser CSS-Durchlauf, dann ein gedeckelter LLM-Durchlauf nur für die fehlenden Felder. ein Scraper + Selektor-Glue + ein LLM-Extraktions-Prompt
/v2/ingest Verwandelt eine Website in RAG-fertige Chunks und gibt eine JSONL-Datei aus, die sich in LangChain, LlamaIndex oder einen Vektor-DB-Import laden lässt. ein Crawler + ein Scraper + dein eigener Chunker
/v2/watch Überwacht eine URL in festem Takt, vergleicht jeden Render mit dem letzten und benachrichtigt dich per Webhook oder E-Mail, wenn sich etwas ändert. ein Cron-Job + ein Storage-Bucket + ein Diff-und-Alert-Skript

Wenn du Firecrawl genutzt hast, ist die Zuordnung direkt: /v2/lookup entspricht /search, /v2/distill entspricht /extract und /v2/ingest entspricht /crawl.

Wie V2 mit V1 zusammenhängt

V2 ist rein additiv. Die V1-Konvertierungsendpunkte — html-to-pdf, url-to-pdf, Bildkonvertierungen, Dokumentkonvertierungen — bleiben unverändert und von all dem unberührt. Du migrierst nicht zu V2; du fügst es neben V1 hinzu, wenn du es brauchst.

Die beiden Hälften teilen die Teile, die für die Integration wichtig sind:

  • Dieselbe Authentifizierung. Ein privater sk_live_-Schlüssel im X-API-Key-Header oder ein öffentlicher pk_-Schlüssel, der gegen ein JWT-Bearer-Token getauscht wird, funktioniert über V1 und V2 hinweg identisch. Siehe den Authentifizierungs-Leitfaden für den vollständigen Ablauf, inklusive Domain-Locking und Token-Refresh.
  • Dieselbe Schlüssel-Allowlist. Jeder API-Schlüssel trägt eine Liste erlaubter Endpunkte. Ein V2-Pfad, der nicht auf der Liste des Schlüssels steht, wird mit 403 abgelehnt, genau wie es bei einem V1-Pfad der Fall wäre.

Was sie nicht teilen, ist der Zähler. V2-Endpunkte werden über eigene Zähler abgerechnet, vollständig getrennt von V1s conversions_used:

Zähler Endpunkt Einheit
perceive_operations /v2/perceive eine Render-Operation (ein Cache-Treffer zählt ebenfalls)
lookup_queries /v2/lookup eine Suche (automatisch wahrgenommene Seiten belasten zusätzlich perceive_operations)
distill_operations /v2/distill eine destillierte URL (nur bei Abschluss)
ingest_pages /v2/ingest eine gerenderte, gechunkte und bereitgestellte Seite

Ein V2-Aufruf verringert niemals conversions_used, und reine V1-Konvertierungspläne enthalten null V2-Kontingent — ein V2-fähiger Plan ist es, der diese Zähler trägt. Zwei Endpunkte sind über ein Plan-Limit statt über einen Zähler pro Operation geregelt: /v2/discover ist HTTP-only und speichert nichts, also läuft es über ein discover_enabled-Plan-Flag; /v2/watch ist durch max_watchers begrenzt — die Obergrenze, wie viele aktive Watcher ein Projekt gleichzeitig hält — zusammen mit dem stündlichen Mindest-Prüftakt. Pro-Stufe-Kontingente für jeden Zähler und jedes Limit findest du auf der Preisseite.

Gemeinsame Designentscheidungen über V2 hinweg

Die sechs Endpunkte bauen auf denselben Primitiven auf, sodass eine Entscheidung, die du einmal lernst, für alle gilt.

Ein Render durch einen gemeinsamen Singleton. Jeder Endpunkt, der einen echten Browser braucht — perceive, das Auto-Perceive von lookup, distill, ingest, watch — rendert durch denselben Headless-Chrome-Singleton und dieselbe Capture-Pipeline hinter dem V1-url-to-pdf-Endpunkt. Cookie-Banner werden weggeklickt, die Seite wird gescrollt, um Lazy-Content auszulösen, und Bildern wird Zeit zum Laden gegeben. Discover ist die bewusste Ausnahme: Es berührt den Browser überhaupt nicht.

Vorsignierte Download-URLs. Binär- und Textartefakte (Markdown, HTML, Screenshots, PDFs, das JSONL aus ingest) werden in den Speicher hochgeladen und als vorsignierte URL zurückgegeben — ein kurzlebiger, signierter Link zum Objektspeicher, der zum Download keine separate Authentifizierung braucht. Jede signierte URL läuft nach 15 Minuten ab (expires_in: 900). Rufe die Operation oder den Job erneut ab, um einen frischen Satz zu erzeugen; das erneute Signieren rendert nichts neu und kostet kein Kontingent.

SSRF-Schutz auf jeder URL. Vor jedem Fetch oder Render wird jede URL geprüft — Schema, eingebettete Zugangsdaten, blockierte Hostnamen und die aufgelöste IP. Eine URL, die zu einer privaten, Loopback-, Link-Local- oder Cloud-Metadaten-Adresse auflöst, wird mit 400 abgelehnt. Das gilt für Seeds, gecrawlte Links, distill-Ziele und watch-Ziele gleichermaßen.

Render-Qualitätsbewertung. Jeder Render trägt einen render_quality-Wert von 0.0 bis 1.0. Ein niedriger Wert markiert eine Seite, die durch Anti-Bot-Schutz blockiert oder hinter einer Login-Wand verborgen wirkt, sodass du eine echte Erfassung von einer Challenge-Seite unterscheiden kannst. Watch geht weiter: ein Render unterhalb der Qualitätsschwelle von 0.4 wird als reine Prüfung erfasst und wird niemals eine Diff-Baseline, sodass eine einmalige Blockade keinen falschen Änderungsalarm auslöst.

Zugangsdatenfrei, wo es zählt. Perceive und distill akzeptieren auth, cookies und benutzerdefinierte headers für Seiten hinter einem Login. Ingest und watch tun dies bewusst nicht — ihre Jobs sind langlebig und wiederkehrend, sodass nichts Geheimes jemals für ein Resume oder eine erneute Prüfung auf die Festplatte geschrieben wird. Brauchst du Zugangsdaten für eine Seite in einem ingest-Satz? Rendere sie stattdessen über den perceive-Endpunkt.

Ehrliches Handhaben von „reserviert, noch nicht live". Wo ein Parameter vom Schema akzeptiert, aber noch nicht verdrahtet ist, sagt V2 es dir, statt ihn stillschweigend zu ignorieren. Perceives proxy_url, geolocation und action_chain geben heute 422 zurück; seine extract-Namen prices, contacts und technologies landen in warnings und werden verworfen. Du weißt immer, welcher Schalter noch nicht bereit ist.

Beta. V2 befindet sich in der Beta. Pinne deine Integration auf die dokumentierten Feld- namen und Statuscodes, lies warnings bei jeder Antwort und erwarte, dass Antwortfelder an Form gewinnen — wenn auch nicht brechen — bevor V2 die Beta verlässt. Neue Felder können auftauchen; dokumentierte ändern ihre Bedeutung nicht stillschweigend.

Was als Nächstes kommt

Um ehrlich zu sein: V2 ist nicht fertig. Drei Fähigkeiten stehen auf der Roadmap und sind noch nicht verfügbar — entwickle nicht gegen sie:

  • Browser-Automatisierung — ein Paar aus /v2/pilot und /v2/conduct für mehrstufige Interaktion (klicken, tippen, navigieren) statt des Einmal-Renders, den die aktuellen Endpunkte ausführen. Die Request- und Response- Formen sind nicht festgelegt, deshalb werden sie hier nicht dokumentiert.
  • Extraktions-Feedback — ein Endpunkt, um ein distill-Ergebnis zu korrigieren und die Korrektur in zukünftige Extraktionen zurückzuspeisen. Benannt, nicht ausgeliefert.

Wenn diese landen, bekommen sie eigene Referenzseiten, genauso wie die sechs oben genannten Endpunkte. Bis dahin sind die aktuellen sechs die gesamte Oberfläche — alles, was du hier über pilot, conduct oder feedback liest, ist eine Roadmap- Notiz, kein Vertrag.

Schnellstart

Greife zum richtigen Endpunkt nach der Form der Aufgabe:

Wenn du noch keinen ersten Aufruf gemacht hast, führt dich der Schnellstart-Leitfaden durch das Holen eines Schlüssels und das Ausführen einer Anfrage von Anfang bis Ende. Jede Endpunktseite beginnt mit ihrem eigenen kleinsten nützlichen curl-Aufruf, sodass du einen einfügen und innerhalb einer Minute eine echte Antwort zurückhaben kannst.

← Image Conversions Perceive (V2) →