--- seo_title: Alle API-Endpunkte: Perceive, Ingest, Convert | EnConvert meta_desc: Alle EnConvert-Endpunkte an einem Ort: Perceive liest eine Seite, Ingest crawlt eine Website, dazu 51 Convert-Routen und der gemeinsame Request-Vertrag. keywords: enconvert api endpunkte, liste aller api endpunkte, x-api-key header verwenden, api basis url enconvert, multipart form data upload api, presigned url antwort api, gemeinsame api request parameter, health check endpunkt api, api antwort envelope json --- # EnConvert API-Endpunkte EnConvert hat drei Endpunktgruppen. Perceive liest eine einzelne Webseite, Ingest crawlt eine gesamte Website in Chunks, und Convert verwandelt Dateien und URLs in andere Formate. Sie teilen sich eine Basis-URL, einen API-Schlüssel und ein monatliches Ops-Kontingent, deshalb gilt der Request-Vertrag weiter unten für alle drei. --- ## Perceive `POST /v2/perceive` rendert eine URL einmal in einem Headless-Browser und gibt aus diesem einen Render alles zurück, was du angefordert hast: Markdown, bereinigtes oder rohes HTML, einen Screenshot, ein PDF, das Link- und Bildinventar sowie strukturierte Seitendaten. Insgesamt fünf Routen, darunter ein Batch-Endpunkt, der eine Liste von URLs unter einem gemeinsamen Satz Optionen entgegennimmt, gedeckelt durch das Batch-Limit deines Plans. Siehe [Perceive](/de/docs/endpoints/perceive.md). ## Ingest `POST /v2/ingest` crawlt eine Website und schreibt jede Seite in eine einzige JSONL-Datei mit RAG-fertigen Chunks; `POST /v2/ingest/files` tut dasselbe für Dokumente, die du hochlädst. Ingest ist immer asynchron: Der POST antwortet mit `202` und einer `job_id`, und du fragst sie entweder ab oder nimmst einen signierten Webhook. Acht Routen, inklusive Rotation des Webhook-Secrets und manueller Neuzustellung. Siehe [Ingest](/de/docs/endpoints/ingest.md). ## Convert 51 Konvertierungs-Endpunkte, alle in der Form `POST /v1/convert/`, gegliedert in vier Familien: Webseiten, Dokumente, Datenformate und Bilder. Jeder nimmt einen Datei-Upload oder eine URL entgegen und schreibt das Ergebnis in den Speicher. Siehe [Convert](/de/docs/endpoints/convert.md). ## In Entwicklung Distill, Lookup, Watch und Discover stehen in privater Beta und werden hier nicht behandelt. Sie sind unter [Demnächst](/de/docs/coming-soon.md) beschrieben, zusammen mit der Phase, zu der sie jeweils gehören. --- ## Gemeinsame Request-Parameter Alles in diesem Abschnitt gilt über die drei Gruppen hinweg. Was nur für eine einzelne Konvertierung gilt, steht auf der Seite des jeweiligen Endpunkts. ### Basis-URL ``` https://api.enconvert.com ``` Jeder Pfad auf dieser Seite ist relativ zu diesem Host. Das Gateway hält eine Anfrage höchstens 300 Sekunden offen; hat bis dahin keine Antwort begonnen, bekommst du `504` mit `{"error": "Request timeout"}`. ### Authentifizierung Jede Anfrage trägt einen der beiden Credential-Header. Das Bearer-Token wird zuerst gelesen, der API-Schlüssel als Zweites. Sendest du keinen von beiden, antwortet die API mit `401` und `Authentication required`. | Header | Erforderlich | Beschreibung | |--------|----------|-------------| | `X-API-Key` | Einer der beiden | Dein API-Schlüssel. Private Schlüssel beginnen mit `sk_`, öffentliche mit `pk_`. | | `Authorization` | Einer der beiden | `Bearer `, wobei das Token ein JWT ist, das unter `POST /v1/auth/token` aus einem öffentlichen Schlüssel erzeugt wird. Zugriffstoken gelten eine Stunde. | | `Content-Type` | Ja | `application/json` für JSON-Bodies, `multipart/form-data` für Datei-Uploads. | | `X-Parent-Origin` | Nur Widgets | Die übergeordnete Domain, die das Widget einbettet, erforderlich für den Token-Austausch mit öffentlichem Schlüssel. |
Private Schlüssel gehören ausschließlich auf den Server. Jede Anfrage, die einen Origin-Header trägt und dabei einen sk_-Schlüssel vorzeigt, wird mit 403 Private API keys cannot be used from browsers abgelehnt. Tausche in Client-seitigem Code stattdessen einen öffentlichen Schlüssel gegen ein JWT.
Das vollständige Schlüsselmodell, inklusive Domain-Allowlists und Endpunkt-Scopes je Schlüssel, steht unter [Authentifizierung](/de/docs/authentication.md). ### Content-Types Es gibt zwei Request-Formen. **JSON-Body (`application/json`)** - Jeder `/v2`-Endpunkt außer `POST /v2/ingest/files`. - Die fünf Endpunkte zur Webseiten-Konvertierung. Ihr Feld `url` nimmt einen URL-String oder ein Array von URL-Strings entgegen. **Multipart-Formular (`multipart/form-data`)** - Die 46 Endpunkte zur Dateikonvertierung, die den Upload aus einem Feld `file` lesen. - `POST /v2/ingest/files`, das eine Liste von Uploads aus einem Feld `files` liest. Uploads werden anhand der Dateiendung und über eine Magic-Byte-Prüfung der ersten Bytes geprüft. Eine Abweichung mit hoher Konfidenz, etwa eine Datei mit dem Namen `.pdf`, deren Bytes ein PNG sind, ergibt `400`. Textformate wie JSON, CSV, XML, YAML, TOML, Markdown, HTML und SVG tragen keine Byte-Signatur, kommen also durch die Prüfung und scheitern erst später im Konverter, wenn der Inhalt fehlerhaft ist. ### Gemeinsame Parameter | Parameter | Gilt für | Wirkung | |-----------|------------|--------------| | `output_filename` | V1-Convert-Endpunkte | Benennt die Ausgabedatei. Ein UTC-Zeitstempel wird immer angehängt: `{output_filename}_{YYYYMMDD_HHMMSSmmm}.{ext}`. Enthält dein Name bereits die Zielerweiterung, wird sie zuvor entfernt, sodass du nie eine doppelte Erweiterung bekommst. | | `direct_download` | Alle V1-Convert-Endpunkte, `POST /v2/perceive` | Gibt die Artefakt-Bytes als Response-Body zurück statt eines JSON-Envelopes. Der Standardwert hängt vom Endpunkt ab: `true` bei Datei-Uploads, `false` bei den URL-Endpunkten mit privatem Schlüssel. Siehe [Signierte URLs](/de/docs/concepts/signed-urls.md). | | `async_mode`, `callback_url`, `notification_email` | V1-URL-Endpunkte | Stellen die Arbeit in die Warteschlange, statt auf sie zu warten, und melden dir, wenn sie fertig ist. Siehe [Synchrone und asynchrone Jobs](/de/docs/concepts/sync-and-async.md) und [Webhooks](/de/docs/guides/webhooks.md). | | `pdf_options` | Endpunkte, die PDF erzeugen | Seitengröße, Ränder, Ausrichtung, Skalierung, Kopf- und Fußzeile, Graustufen. Die Feldliste steht auf der Seite jedes PDF-Endpunkts. | Standard-Ausgabenamen, wenn du kein `output_filename` übergibst: - **Datei-Uploads:** abgeleitet vom Eingabe-Dateinamen, aus `report.docx` wird also `report_20260405_123456789.pdf`. - **URL-Konvertierungen:** abgeleitet vom Domainnamen, also `example_20260405_123456789.pdf`. - **Fallback:** `output_20260405_123456789.{ext}`. ### Antwort-Envelope Eine synchrone V1-Konvertierung antwortet mit `200` und dem Ort der Datei statt mit der Datei selbst: ```json { "presigned_url": "https://spaces.example.com/...signed...", "object_key": "live/files/4127/url-to-pdf/example_20260405_123456789.pdf", "filename": "example_20260405_123456789.pdf", "file_size": 48213, "conversion_time_seconds": 2.41 } ``` Konvertierungsantworten wiederholen diese Metadaten in Headern: | Header | Beschreibung | |--------|-------------| | `Content-Disposition` | `inline; filename="{filename}"` | | `X-Object-Key` | Speicherpfad der konvertierten Datei | | `X-File-Size` | Größe der konvertierten Datei in Bytes | | `X-Conversion-Time` | Für die Konvertierung benötigte Zeit in Sekunden | | `X-Filename` | Generierter Dateiname | V2-Endpunkte geben eigene JSON-Envelopes zurück, dokumentiert auf ihren jeweiligen Seiten, aber jedes gespeicherte Artefakt in diesen Envelopes hat dieselbe Form: ```json { "url": "https://spaces.example.com/...signed...", "object_key": "live/files/4127/v2-perceive/per_3f9a..._markdown.md", "size_bytes": 8421, "content_type": "text/markdown; charset=utf-8", "expires_in": 900 } ```
Signierte URLs leben 15 Minuten. Sie funktionieren innerhalb dieses Fensters mehr als einmal, und ein erneutes Abfragen des Status-Endpunkts eines Jobs erzeugt eine frische URL auf dasselbe Objekt. Lade die Datei zügig herunter oder kopiere sie in deinen eigenen Speicher.
Mehr zu Ablauf, Wiederverwendung und Aufbewahrung: [Signierte URLs](/de/docs/concepts/signed-urls.md). ### Fehler Fehlschläge kommen als JSON-Objekt mit einem Feld `detail` zurück: ```json { "detail": "Monthly operations limit reached (500/500). Upgrade your plan to continue." } ``` `413 Payload Too Large` ist die Ausnahme: Sein `detail` ist ein Objekt mit `error`, `file_size`, `max_size`, `tier` und `key_type`. Die Statuscodes und die Meldungen dahinter stehen unter [Fehler](/de/docs/reference/errors.md). Die Plan-Limits, die `402`, `413` und `429` auslösen, stehen unter [Rate-Limits und Kontingente](/de/docs/reference/rate-limits.md). --- ## Service-Endpunkte | Endpunkt | Methode | Beschreibung | |----------|--------|-------------| | `/health` | `GET` | Health-Check. Liefert `200`, wenn Datenbank, Speicher und Browser alle antworten, und `503`, wenn eines davon nicht antwortet. Keine Authentifizierung. | | `/v1/whoami` | `GET` | Liefert `{"project_id": ..., "plan_slug": ...}` für den privaten Schlüssel, den du vorzeigst. Ein öffentlicher Schlüssel oder ein JWT bekommt `403`. | Das Erzeugen, Erneuern und Prüfen von Token liegt unter `/v1/auth/` und wird unter [Authentifizierung](/de/docs/authentication.md) behandelt. Die Widget-Config- und Token-Routen liegen unter `/v1/widget/` und werden unter [Integrationen](/de/docs/guides/integrations.md) behandelt. ## Häufig gestellte Fragen ### Welche Endpunkte akzeptieren Datei-Uploads? Die 46 Endpunkte zur Dateikonvertierung und `POST /v2/ingest/files`. Sie lesen `multipart/form-data`. Alles andere nimmt einen JSON-Body entgegen, auch die fünf Endpunkte zur Webseiten-Konvertierung, die einen `url`-String oder ein Array von URLs akzeptieren. ### Verwenden die V2-Endpunkte denselben API-Schlüssel wie die Konvertierungs-Endpunkte? Ja. Ein Schlüssel, ein Projekt, ein monatliches Kontingent. Jede Arbeitseinheit kostet eine Op, egal ob es eine Dateikonvertierung, eine per perceive verarbeitete URL oder eine ingestierte Seite ist. Es gibt keine Zähler pro Endpunkt und keine Credit-Multiplikatoren. ### Wie prüfe ich, ob die API erreichbar ist? Rufe `GET /health` auf. Der Endpunkt liefert `200`, wenn Datenbank, Speicher und Browser alle antworten, und `503`, wenn eines davon nicht antwortet, und er braucht keine Authentifizierung. ### Wie lange bleiben die Download-URLs gültig? 15 Minuten. Eine URL lässt sich vor ihrem Ablauf mehrfach verwenden, und ein erneutes Abfragen des Status-Endpunkts eines Jobs liefert eine frisch signierte URL für dieselbe Datei. ### Warum liefert eine Konvertierung eine URL statt der Datei? Zwei Gründe. Eine große Konvertierung kann 60 bis 120 Sekunden laufen, lang genug, dass ein Reverse Proxy vor deinem Code eine gestreamte Antwort aufgibt, und dasselbe Ergebnis muss oft mehr als einmal abgeholt werden. Also gehen die Bytes in den Speicher, und du bekommst eine signierte URL darauf. Wo dir ein einziger Roundtrip besser passt, liefert `direct_download` die Bytes inline.