--- seo_title: V1 vs. V2: Dateien konvertieren oder Web lesen | EnConvert meta_desc: V1 konvertiert Dateien und URLs zwischen Formaten. V2 liest das Live-Web für Agenten und RAG-Pipelines. Welche Hälfte du aufrufst und was als Nächstes kommt. keywords: v1 vs v2 api, dateikonvertierungs api vs web scraping api, enconvert api hälften, web daten api für ki agenten, url zu markdown api, rag ingestion api, welchen api endpunkt verwenden, ein api schlüssel zwei apis, welche v2 endpunkte sind live --- # 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.
Heute live: ganz V1, dazu alle sechs V2-Endpunkte. Perceive und Ingest sind allgemein verfügbar. Distill, Lookup, Watch und Discover sind aufrufbar, stehen aber in privater Beta, sind unter Demnächst dokumentiert und können ihre Formen ohne Vorankündigung ändern.
--- ## Die Entscheidungsregel Kennst du das gewünschte Ausgabeformat bereits, ist das V1. Willst du wissen, was auf einer Seite steht, ist das V2. | Was du vorhast | Hälfte | Startpunkt | |---|---|---| | Diese URL in ein PDF verwandeln | V1 | [url-to-pdf](/de/docs/endpoints/convert/web-pages/url-to-pdf.md) | | Dieses DOCX in ein PDF verwandeln | V1 | [Dokumente](/de/docs/endpoints/convert/documents.md) | | Dieses JSON in YAML verwandeln | V1 | [Datenformate](/de/docs/endpoints/convert/data-formats.md) | | Dieses HEIC in ein WebP verwandeln | V1 | [Bilder](/de/docs/endpoints/convert/images.md) | | Diese Seite als Markdown für ein LLM lesen | V2 | [Perceive](/de/docs/endpoints/perceive.md) | | Markdown, einen Screenshot, Links und Metadaten aus einem Render holen | V2 | [Perceive](/de/docs/endpoints/perceive.md) | | Eine ganze Website in RAG-Chunks verwandeln | V2 | [Ingest](/de/docs/endpoints/ingest.md) | 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. | Familie | Endpunkte | Eingabe | |---|---|---| | [Webseiten](/de/docs/endpoints/convert/web-pages.md) | 5 | Eine URL (oder eine Liste von URLs) in einem JSON-Body | | [Dokumente](/de/docs/endpoints/convert/documents.md) | 13 | Ein Datei-Upload (`multipart/form-data`) | | [Datenformate](/de/docs/endpoints/convert/data-formats.md) | 11 | Ein Datei-Upload (`multipart/form-data`) | | [Bilder](/de/docs/endpoints/convert/images.md) | 22 | Ein Datei-Upload (`multipart/form-data`) | Davon sind `website-to-pdf` und `website-to-screenshot` die beiden Crawler: Sie ermitteln die Seiten unterhalb einer Domain und antworten immer [asynchron](/de/docs/concepts/sync-and-async.md) 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](/de/docs/endpoints/convert/matrix.md). Ein V1-Aufruf sieht so aus: ```bash 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"}' ``` ```json { "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: ```bash 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: ```json { "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. | Endpunkt | Status | Funktion | |---|---|---| | [`POST /v2/perceive`](/de/docs/endpoints/perceive.md) | Live | Rendert eine URL einmal und gibt jede angeforderte Ausgabe zurück: Markdown, bereinigtes oder rohes HTML, Screenshot, PDF, Links, Bilder, strukturierte Daten. | | [`POST /v2/ingest`](/de/docs/endpoints/ingest.md) | Live | Crawlt eine Website (oder nimmt hochgeladene Dateien entgegen) und erzeugt eine JSONL-Datei mit RAG-fertigen Chunks, asynchron hinter einer `job_id`. | | Distill | Private Beta | [Referenz](/de/docs/coming-soon/distill.md) | | Lookup | Private Beta | [Referenz](/de/docs/coming-soon/lookup.md) | | Watch | Private Beta | [Referenz](/de/docs/coming-soon/watch.md) | | Discover | Private Beta | [Referenz](/de/docs/coming-soon/discover.md) |
Die unteren vier Zeilen sind private Beta. Distill, Lookup, Watch und Discover beantworten heute echte Requests, sind aber nicht angekündigt, nicht allgemein verfügbar, und ihre Request- und Response-Formen können sich ohne Vorankündigung ändern, halte sie also aus allem heraus, was tragend ist. Watch braucht einen kostenpflichtigen Tarif; die anderen drei laufen in jedem Tarif, Founding eingeschlossen. Details stehen unter Demnächst.
--- ## 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](/de/docs/authentication.md) 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](/de/docs/reference/rate-limits.md). **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](/de/docs/concepts/signed-urls.md). --- ## 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](/de/docs/endpoints/convert/web-pages/url-to-pdf.md). 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](/de/docs/endpoints/perceive.md). **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.
V2 ist in der Beta. Pinne deine Integration auf die dokumentierten Feldnamen und Statuscodes, lies warnings bei jeder Antwort und erwarte, dass Response-Bodies Felder gewinnen, bevor V2 die Beta verlässt. Neue Felder können auftauchen; dokumentierte ändern ihre Bedeutung nicht stillschweigend.
--- ## Wo du anfängst - **Eine Datei oder eine URL konvertieren:** [die Convert-Endpunkte](/de/docs/endpoints/convert.md). - **Eine Seite lesen:** [der Perceive-Endpunkt](/de/docs/endpoints/perceive.md). - **Einen RAG-Korpus aus einer Website aufbauen:** [der Ingest-Endpunkt](/de/docs/endpoints/ingest.md). - **Die Endpunkte in privater Beta ausprobieren:** [Demnächst](/de/docs/coming-soon.md). Wenn du noch keinen ersten Aufruf gemacht hast, führt dich [der Schnellstart](/de/docs/quickstart.md) 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](/de/docs/reference/rate-limits.md). ### 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](/de/docs/coming-soon.md) dokumentiert, jederzeit formveränderlich, und Watch braucht zusätzlich einen kostenpflichtigen Tarif.