Unterstützte Formate#

Jede Dateiendung, die die API akzeptiert, und jedes Format, das sie zurückgibt, eine Tabelle pro Konverter-Familie. Die Listen hier sind genau die, gegen die der Code prüft: Eine fehlende Dateiendung wird also tatsächlich abgelehnt und ist nicht bloß undokumentiert.

Wenn du stattdessen die Paarung suchst (diese Eingabe, jene Ausgabe und der Endpunkt-Pfad, der beide verbindet), enthält die Konvertierungsmatrix alle 51 Endpunkte in einer übersichtlichen Tabelle.

Webseiten#

Fünf Endpunkte, die eine URL in einem JSON-Body entgegennehmen statt eines Datei-Uploads.

Endpunkt	Eingabe	Ausgabe
`POST /v1/convert/url-to-pdf`	Eine URL oder ein Array von URLs	PDF (`application/pdf`)
`POST /v1/convert/url-to-screenshot`	Eine URL oder ein Array von URLs	PNG (`image/png`)
`POST /v1/convert/url-to-markdown`	Eine URL oder ein Array von URLs	Markdown (`text/markdown; charset=utf-8`)
`POST /v1/convert/website-to-pdf`	Eine Site-URL, gecrawlt oder aus `sitemap.xml` gelesen	ZIP mit PDFs
`POST /v1/convert/website-to-screenshot`	Eine Site-URL, gecrawlt oder aus `sitemap.xml` gelesen	ZIP mit PNGs

Screenshots sind PNG. Eine JPEG- oder WebP-Screenshot-Option gibt es nicht: Der Capture-Aufruf ist fest auf PNG verdrahtet. Die beiden website-to-*-Endpunkte arbeiten ausschließlich asynchron und antworten immer mit 202, einer batch_id und einem output_format von zip.

Dokumente zu PDF#

Elf Endpunkte mit festem Ziel, jeder ein multipart/form-data-Upload mit dem Dokument im Feld file. Die Ausgabe ist immer ein einzelnes PDF. Der Allrounder anything-to-pdf ist der zwölfte und hat weiter unten einen eigenen Abschnitt.

Endpunkt	Akzeptierte Eingabe	Engine
`POST /v1/convert/html-to-pdf`	`.html`, `.htm`	WeasyPrint
`POST /v1/convert/markdown-to-pdf`	`.md`, `.markdown`	WeasyPrint
`POST /v1/convert/doc-to-pdf`	`.doc`, `.docx`	LibreOffice
`POST /v1/convert/excel-to-pdf`	`.xls`, `.xlsx`	LibreOffice
`POST /v1/convert/ppt-to-pdf`	`.ppt`, `.pptx`	LibreOffice
`POST /v1/convert/odt-to-pdf`	`.odt`	LibreOffice
`POST /v1/convert/ods-to-pdf`	`.ods`	LibreOffice
`POST /v1/convert/odp-to-pdf`	`.odp`	LibreOffice
`POST /v1/convert/ots-to-pdf`	`.ots`	LibreOffice
`POST /v1/convert/pages-to-pdf`	`.pages`	LibreOffice
`POST /v1/convert/numbers-to-pdf`	`.numbers`	LibreOffice

Die Engine entscheidet, welche pdf_options zulässig sind. HTML und Markdown laufen über WeasyPrint und akzeptieren Seitengröße, Ausrichtung, Ränder, Skalierung sowie Kopf- und Fußzeile. Die neun auf LibreOffice basierenden Endpunkte übernehmen die Seitengeometrie aus dem Quelldokument, berücksichtigen daher nur grayscale und liefern 400, wenn eine Geometrie-Option explizit gesetzt wird.

anything-to-pdf#

POST /v1/convert/anything-to-pdf akzeptiert 36 Dateiendungen und liefert immer ein PDF. Nur Datei-Upload: URLs nimmt der Endpunkt nicht entgegen.

.bmp   .csv   .doc   .docx  .epub  .gif
.heic  .heif  .htm   .html  .jpeg  .jpg
.markdown     .md    .mdown .mkd   .numbers
.odp   .ods   .odt   .ots   .pages .pdf
.png   .ppt   .pptx  .rtf   .svg   .text
.tif   .tiff  .txt   .webp  .xhtml .xls
.xlsx

Die Dateiendung bestimmt die Engine:

Eingabegruppe	Dateiendungen	Engine
Office, OpenDocument, iWork, RTF, CSV	`.doc` `.docx` `.xls` `.xlsx` `.ppt` `.pptx` `.odt` `.ods` `.odp` `.ots` `.pages` `.numbers` `.rtf` `.csv`	LibreOffice headless
HTML	`.html` `.htm` `.xhtml`	WeasyPrint
Markdown	`.md` `.markdown` `.mdown` `.mkd`	WeasyPrint
Reiner Text	`.txt` `.text`	In einen Monospace-Block gepackt, dann WeasyPrint
EPUB	`.epub`	EPUB zu Markdown, dann WeasyPrint
Rasterbilder	`.png` `.jpg` `.jpeg` `.gif` `.bmp` `.tiff` `.tif` `.webp` `.heic` `.heif`	Pillow
SVG	`.svg`	CairoSVG
PDF	`.pdf`	Validierte Durchreichung

Zwei Folgen dieses Routings solltest du kennen, bevor du eine Datei sendest:

Die Seitengeometrie (page_size, page_width, page_height, orientation, Ränder, scale, header, footer) wird nur für HTML, Markdown, reinen Text, EPUB, Bilder und SVG als Eingabe berücksichtigt. Setzt du eine davon explizit bei einer Office- oder PDF-Eingabe, liefert der Request 400. grayscale funktioniert bei jeder Eingabe.
Ein PDF-Upload wird angenommen und direkt durchgereicht, nachdem geprüft wurde, dass die Bytes mit %PDF- beginnen. Zusammen mit grayscale ist dieser Endpunkt damit der Weg, ein bestehendes PDF in Graustufen umzuwandeln.

anything-to-markdown#

POST /v1/convert/anything-to-markdown akzeptiert 22 Dateiendungen und liefert immer eine einzelne UTF-8-.md-Datei.

.csv   .doc   .docx  .epub  .htm   .html
.markdown     .md    .mdown .mkd   .odp
.ods   .odt   .pdf   .ppt   .pptx  .rtf
.text  .txt   .xhtml .xls   .xlsx

Gruppiert danach, wie die jeweilige Eingabe gelesen wird:

Eingabegruppe	Dateiendungen	Weg
Text und Markdown	`.txt` `.text` `.md` `.markdown` `.mdown` `.mkd`	Direkt gelesen
HTML	`.html` `.htm` `.xhtml`	HTML zu Markdown
Legacy und OpenDocument	`.doc` `.ppt` `.xls` `.odt` `.ods` `.odp` `.rtf`	LibreOffice zu HTML, dann zu Markdown
Native Extraktoren	`.pdf` `.docx` `.pptx` `.xlsx` `.csv` `.epub`	Formatspezifischer Extraktor

Drei Punkte, die du einplanen solltest:

Bilder werden abgelehnt. .png, .jpg, .jpeg, .gif, .bmp, .webp, .tiff und .tif liefern 400 mit Image OCR ('<ext>') is not yet supported on this endpoint. Dieser Endpunkt macht kein OCR, eine gescannte Seite in einer Bilddatei hat hier also derzeit keinen Weg zu Text.
.ots, .pages und .numbers werden hier nicht akzeptiert, obwohl anything-to-pdf alle drei entgegennimmt. Schick sie zuerst durch anything-to-pdf, denn .pdf steht auf der Liste oben.
Die Ausgabe wird vor der Rückgabe normalisiert: CRLF wird zu LF, drei oder mehr aufeinanderfolgende Leerzeilen werden zusammengefasst, und die Datei endet mit einem Zeilenumbruch.

Die Extraktion läuft unter Ressourcen-Obergrenzen, die vor bösartigen Uploads schützen. ZIP-basierte Eingaben (EPUB, DOCX, XLSX, PPTX) werden über 400 MB deklarierter unkomprimierter Größe oder 10.000 Einträgen abgelehnt. Erzeugte Tabellen kürzen Zellen bei 500 Zeichen und stoppen bei 5.000 Body-Zeilen. Der PDF-Extraktor deckelt bei 2.000 Seiten und 20.000 Wörtern pro Seite.

Datenformate#

Elf Endpunkte, allesamt synchrone Uploads. Die Dateiendung der Datei muss zu dem Endpunkt passen, an den du sie sendest.

Endpunkt	Akzeptierte Eingabe	Ausgabe
`POST /v1/convert/json-to-xml`	`.json`	`.xml`
`POST /v1/convert/xml-to-json`	`.xml`	`.json`
`POST /v1/convert/json-to-yaml`	`.json`	`.yaml`
`POST /v1/convert/yaml-to-json`	`.yaml`, `.yml`	`.json`
`POST /v1/convert/json-to-csv`	`.json`	`.csv`
`POST /v1/convert/csv-to-json`	`.csv`	`.json`
`POST /v1/convert/json-to-toml`	`.json`	`.toml`
`POST /v1/convert/toml-to-json`	`.toml`	`.json`
`POST /v1/convert/csv-to-xml`	`.csv`	`.xml`
`POST /v1/convert/xml-to-csv`	`.xml`	`.csv`
`POST /v1/convert/markdown-to-html`	`.md`, `.markdown`	`.html`

Bilder#

Zweiundzwanzig Endpunkte: zwanzig Konvertierungen zwischen JPEG, PNG, SVG, HEIC und WebP (jedes geordnete Paar), dazu pdf-to-jpeg und compress-image. Lies diese Tabelle als „Wozu kann ich das umwandeln?“.

Eingabe	Verfügbare Ausgaben
JPEG (`.jpeg`, `.jpg`)	PNG, SVG, HEIC, WebP
PNG (`.png`)	JPEG, SVG, HEIC, WebP
SVG (`.svg`)	JPEG, PNG, HEIC, WebP
HEIC (`.heic`, `.heif`)	JPEG, PNG, SVG, WebP
WebP (`.webp`)	JPEG, PNG, SVG, HEIC
PDF (`.pdf`)	JPEG, über `pdf-to-jpeg`
PNG, JPEG, WebP	Dasselbe Format, kleiner, über `compress-image`

Die Endpunktnamen folgen dem Paar: jpeg-to-png, svg-to-webp, heic-to-jpeg und so weiter. Beachte: Die JPEG-Endpunkte schreiben sich jpeg-, nicht jpg-, obwohl sowohl .jpeg- als auch .jpg-Dateien akzeptiert werden.

compress-image behält das Eingabeformat: PNG rein, PNG raus. Das optionale target_size_kb muss mindestens 1 sein; ein kleinerer Wert liefert 400, bevor eine Op verbraucht wird.

pdf-to-jpeg liefert bei einem einseitigen PDF ein rohes JPEG und bei einem mehrseitigen ein ZIP mit page_1.jpeg bis page_N.jpeg. Jede Konverter-Ausgabe, die mit einer ZIP-Signatur beginnt, wird mit der Dateiendung .zip ausgeliefert, weshalb derselbe Endpunkt dir zwei verschiedene Content-Types zurückgeben kann.

Pixel-Obergrenzen#

Diese werden getrennt vom Dateigrößenlimit deines Plans geprüft, denn eine kleine Datei kann zu einer riesigen Bitmap dekodieren.

Limit	Wert	Gilt für
Dekodierte Pixel	40.000.000	Jeder Bild-Endpunkt, geprüft direkt nach dem Öffnen des Bildes
SVG-Ausgabe-Kantenlänge	10.000 px pro Seite	SVG-Rasterisierung (`svg-to-*`)
SVG-Ausgabe-Pixel	25.000.000 insgesamt	SVG-Rasterisierung (`svg-to-*`)
Render-Größe	25.000.000 px pro Seite	`pdf-to-jpeg`, das den Render passend herunterskaliert
Seitenzahl	500 Seiten	`pdf-to-jpeg`

SVG-Anfragen, die eine Kantenlängen-Obergrenze sprengen, liefern 400, bevor eine Op gezählt wird. Gibst du nur width oder nur height an, wird der jeweils andere Wert aus dem intrinsischen Seitenverhältnis des SVG abgeleitet; lässt sich dieses Verhältnis nicht auslesen, schlägt die Anfrage mit einem 400 fehl, das beide Werte verlangt.

Media-Types der Ausgabe#

Direkte Downloads tragen den Media-Type, der aus der Dateiendung der Ausgabe abgeleitet wird.

Dateiendung	Content-Type
`.pdf`	`application/pdf`
`.png`	`image/png`
`.jpeg`, `.jpg`	`image/jpeg`
`.heic`	`image/heic`
`.webp`	`image/webp`
`.svg`	`image/svg+xml`
`.json`	`application/json`
`.xml`	`application/xml`
`.yaml`, `.yml`	`application/x-yaml`
`.csv`	`text/csv`
`.toml`	`application/toml`
`.html`	`text/html`
`.md`	`text/markdown; charset=utf-8`
`.zip`	`application/zip`

Alles, was nicht auf dieser Liste steht, wird als application/octet-stream ausgeliefert.

V2-Eingaben und -Ausgaben#

Die Web-Intelligence-Endpunkte denken in Ausgaben statt in Dateiformaten.

POST /v2/perceive nimmt eine URL entgegen und gibt beliebige Ausgaben aus einer festen Menge zurück: markdown, html_cleaned, html_raw, screenshot, screenshot_full_page, pdf, links, images, structured. Der Standard ist ["markdown", "structured"]. Alles außer structured wird in den Speicher geschrieben und als signierte Download-URL zurückgegeben; structured kommt inline im Response-Body zurück.

POST /v2/ingest/files übernimmt die anything-to-markdown-Liste von oben wortwörtlich, es werden also dieselben 22 Dateiendungen akzeptiert und Bilder auf dieselbe Weise abgelehnt. Ein einzelner Job nimmt bis zu 200 Dateien entgegen, jeder Dateiname bis zu 255 Zeichen, und die Ausgabe des Jobs ist eine einzelne JSONL-Datei mit Chunks.

So funktioniert die Formaterkennung#

Uploads werden zweimal geprüft, und keine der beiden Prüfungen schaut auf den Content-Type des Requests. Eine MIME-Allowlist für Uploads gibt es nirgends in der API.

Zuerst die Dateiendung. Deklariert der Endpunkt eine Liste akzeptierter Endungen und deine steht nicht darauf, schlägt der Request sofort fehl:

{
    "detail": "Invalid file format '.txt' for json-to-xml. Allowed: .json"
}

Dann die Bytes. Die API schnüffelt die ersten Bytes des Uploads und vergleicht den Fund mit dem, was die Dateiendung behauptet hat. Erkannt werden PNG, JPEG, GIF, WebP, HEIC und HEIF, PDF sowie die beiden Office-Containertypen (der ZIP-Container hinter .docx, .xlsx, .pptx, ODF, iWork und EPUB sowie der ältere OLE2-Container hinter .doc, .xls, .ppt).

Textformate überspringen die Byte-Prüfung vollständig. JSON, CSV, XML, YAML, TOML, Markdown, HTML, SVG und reiner Text haben keine verlässliche Signatur, ihre Dateiendung wird daher für bare Münze genommen, und stattdessen meldet der Konverter das Problem.

Die Byte-Prüfung ist bewusst konservativ. Sie lehnt nur eine Abweichung mit hoher Konfidenz ab, also eine erkannte Signatur, die zu einer anderen Gruppe gehört als die angegebene Dateiendung. Ein .png-Upload, dessen Bytes ein JPEG sind, wird abgelehnt. Nicht erkannte Bytes gehen durch. Eine Abweichung liefert 400:

{
    "detail": "File content does not match the 'jpeg-to-png' input type."
}

Eine Datei umzubenennen konvertiert sie nicht. Wenn du photo.webp in photo.png umbenennst, kommst du an der Endungsprüfung vorbei und scheiterst dann an der Byte-Prüfung mit dem 400 von oben. Sende die echte Dateiendung und wähle den Endpunkt, der dazu passt.

Dateinamen werden auf dem Weg in den Speicher umgeschrieben, nicht abgelehnt: Nur der Basisname bleibt übrig, .. und die Zeichen <>:"|?* werden entfernt, und Leerzeichen werden zu Unterstrichen. Den daraus entstehenden Object Key zeigt Datei-Ingestion.

API Documentation