V1 und V2: Dateien konvertieren oder das Web lesen#

Die EnConvert API hat zwei Hälften. V1 (/v1/convert/...) verwandelt eine Datei oder eine URL in ein Format, das du benennst; V2 (/v2/...) liest eine Live-Webseite und gibt Daten zurück, mit denen ein Agent arbeiten kann. Ein Schlüssel deckt beide Hälften unter einer Basis-URL ab, und beide rechnen über denselben Zähler ab.

Die Entscheidungsregel#

Kennst du das gewünschte Ausgabeformat bereits, ist das V1. Willst du wissen, was auf einer Seite steht, ist das V2.

Der unbequeme Grenzfall: url-to-markdown (V1) und perceive (V2) überschneiden sich. Nimm V1, wenn du eine Markdown-Datei willst und sonst nichts. Nimm V2, wenn du zusätzlich den Screenshot, die Links, die Seiten-Metadaten oder die Möglichkeit willst, die Bytes inline zurückzustreamen.

V1: deterministische Konvertierung#

Du sendest Bytes oder eine URL, und der Endpunkt, den du aufrufst, ist das Zielformat. POST /v1/convert/png-to-webp gibt WebP zurück. Nichts entscheidet irgendetwas für dich.

Es gibt 49 Konvertierungs-Endpunkte mit je einem Ziel über vier Familien hinweg, dazu zwei Website-Crawler, die eine gesamte Website durchlaufen und ein ZIP zurückgeben, insgesamt also 51 Routen.

Davon sind website-to-pdf und website-to-screenshot die beiden Crawler: Sie ermitteln die Seiten unterhalb einer Domain und antworten immer asynchron mit 202 und einem ZIP. Jeder andere Endpunkt konvertiert eine Eingabe in eine Ausgabe. Die vollständige Zuordnung von Eingabe zu Ausgabe steht in der Konvertierungsmatrix.

Ein V1-Aufruf sieht so aus:

curl -X POST https://api.enconvert.com/v1/convert/url-to-pdf \
  -H "X-API-Key: sk_your_private_key" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/pricing"}'

{
    "presigned_url": "https://spaces.example.com/...signed...",
    "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
}

Setzt du bei einer synchronen Anfrage mit einer einzelnen URL direct_download=true, ist der Response-Body das PDF selbst statt dieses JSON.

V2: das Live-Web lesen#

V2 rendert eine Seite in echtem Headless-Chrome (JavaScript wird ausgeführt, Lazy-Content wird geladen) und gibt zurück, was darauf steht: Markdown, bereinigtes oder rohes HTML, einen Screenshot, ein PDF, das Link- und Bildinventar, strukturierte Seitendaten oder RAG-fertige Chunks. Du benennst weniger ein Ausgabeformat als die Ausgaben, die du aus einem Render haben willst.

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_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"}
    }
}

Sende JSON, erhalte ein Ergebnis inline oder eine kurzlebige signierte URL zu einem Artefakt zurück. Das ist die Form jedes V2-Endpunkts.

Was heute live ist#

Alle sechs V2-Endpunkte sind aufrufbar. Zwei davon sind allgemein verfügbar: Perceive und Ingest.

Was die beiden Hälften teilen#

V2 ist rein additiv. Die V1-Endpunkte bleiben unverändert und von all dem unberührt. Es gibt keine Migration: Du fügst V2 neben V1 hinzu, wenn du es brauchst.

Ein Schlüssel. Ein privater sk_-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 Authentifizierung für den vollständigen Ablauf, inklusive Domain-Locking und Token-Refresh.

Eine 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.

Ein Zähler. V1-Konvertierungen und V2-Operationen belasten denselben monatlichen Ops-Zähler. Eine Op ist eine Arbeitseinheit: eine Konvertierung, eine per perceive verarbeitete URL, eine ingestierte Seite. Es gibt keine Multiplikatoren pro Endpunkt, ein teurer Render kostet also dieselbe Op wie eine Konvertierung von JSON zu YAML. Die Plan-Kontingente stehen unter Rate-Limits und Kontingente.

Ein Auslieferungsweg. Dateiausgaben aus beiden Hälften werden in den Speicher hochgeladen und als vorsignierte URL zurückgegeben, die nach 15 Minuten abläuft (expires_in: 900). Rufe die Operation, den Job oder den Batch erneut ab, um einen frischen Satz zu erzeugen; das erneute Signieren rendert nichts neu und kostet keine Ops. Details unter Signierte URLs.

Designentscheidungen, die über V2 hinweg gelten#

Lerne sie einmal, und sie gelten in ganz V2.

Ein Render durch einen gemeinsamen Browser. Perceive und Ingest rendern 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.

SSRF-Schutz auf jeder URL. Vor jedem Fetch oder Render wird jede URL auf Schema, eingebettete Zugangsdaten, blockierte Hostnamen und die aufgelöste IP geprüft. Eine URL, die zu einer privaten, Loopback-, Link-Local- oder Cloud-Metadaten-Adresse auflöst, wird mit 400 abgelehnt. Das gilt für Seeds und gecrawlte Links 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.

Zugangsdaten nur dort, wo sie sicher sind. Perceive akzeptiert auth, cookies und benutzerdefinierte headers für Seiten hinter einem Login. Ingest tut das bewusst nicht, denn seine Jobs sind langlebig und fortsetzbar, und nichts Geheimes sollte für eine Fortsetzung gespeichert werden. Brauchst du Zugangsdaten für eine Seite in einem Ingest-Satz? Rendere sie stattdessen über Perceive.

Reservierte Parameter sagen es dir. 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.

Wo du anfängst#

• Eine Datei oder eine URL konvertieren: die Convert-Endpunkte.
• Eine Seite lesen: der Perceive-Endpunkt.
• Einen RAG-Korpus aus einer Website aufbauen: der Ingest-Endpunkt.
• Die Endpunkte in privater Beta ausprobieren: Demnächst.

Wenn du noch keinen ersten Aufruf gemacht hast, führt dich der Schnellstart durch das Holen eines Schlüssels und das Ausführen einer Anfrage von Anfang bis Ende.

Häufig gestellte Fragen#

Brauche ich einen separaten API-Schlüssel für V2?#

Nein. Ein Schlüssel deckt beide Hälften ab. Ein privater sk_-Schlüssel im X-API-Key-Header oder ein JWT, das aus einem öffentlichen pk_-Schlüssel erzeugt wurde, authentifiziert V1 und V2 identisch, vorbehaltlich der Liste erlaubter Endpunkte des Schlüssels.

Ersetzt V2 die V1-API?#

Nein. V2 ist rein additiv, und V1 bleibt unverändert. Willst du ein benanntes Ausgabeformat aus einer Datei oder einer URL, ist V1 weiterhin der richtige Aufruf, und das bleibt auch so.

Wie wird die Nutzung über V1 und V2 hinweg gezählt?#

Beide Hälften belasten einen monatlichen Ops-Zähler, und eine Op ist eine Arbeitseinheit: eine V1-Konvertierung, eine per perceive verarbeitete URL, eine ingestierte Seite. Es gibt keine Gewichtung pro Endpunkt. Siehe Rate-Limits und Kontingente.

Welche V2-Endpunkte kann ich heute aufrufen?#

Alle sechs. Perceive und Ingest sind allgemein verfügbar. Distill, Lookup, Watch und Discover stehen in privater Beta: mit deinem normalen Schlüssel aufrufbar, unter Demnächst dokumentiert, jederzeit formveränderlich, und Watch braucht zusätzlich einen kostenpflichtigen Tarif.