In der Sandbox ausführen

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.

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.

Convert#

51 Konvertierungs-Endpunkte, alle in der Form POST /v1/convert/<id>, 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.

In Entwicklung#

Distill, Lookup, Watch und Discover stehen in privater Beta und werden hier nicht behandelt. Sie sind unter Demnächst 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 <token>`, 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.

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.
`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 und Webhooks.
`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:

{
    "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:

{
    "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.

Fehler#

Fehlschläge kommen als JSON-Objekt mit einem Feld detail zurück:

{
    "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. Die Plan-Limits, die 402, 413 und 429 auslösen, stehen unter Rate-Limits und Kontingente.

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 behandelt. Die Widget-Config- und Token-Routen liegen unter /v1/widget/ und werden unter Integrationen 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.

← V1 and V2 Perceive →

API Documentation