API für Datenformat-Konvertierung#
Die Datenformat-Endpunkte konvertieren strukturierte Datendateien zwischen JSON, XML, YAML, CSV und TOML und rendern zudem Markdown zu vollständig gestyltem HTML. Jede Konvertierung ist eine einzelne POST-Anfrage mit einem multipart/form-data-Datei-Upload: Sende deine Datei, erhalte das konvertierte Ergebnis als rohe Bytes zurück, oder fordere stattdessen eine presigned Download-URL an. Alle elf Endpunkte folgen derselben Request-Struktur, Authentifizierung und demselben Fehlermodell, sodass die Integration eines zweiten Formats nach dem ersten nur Minuten dauert.
Unterstützte Konvertierungen#
| Konvertierung | Endpunkt | Beschreibung |
|---|---|---|
| JSON zu XML | POST /v1/convert/json-to-xml |
Konvertiert JSON zu XML, wobei Objekte zu Kindelementen von <root> werden, Arrays in <item>-Elemente verpackt werden und Skalare in <value> stehen. |
| XML zu JSON | POST /v1/convert/xml-to-json |
Konvertiert XML zu JSON, wobei Attribute auf @-präfixierte Keys, Textinhalte auf #text und wiederholte Sibling-Elemente auf Arrays abgebildet werden. |
| JSON zu YAML | POST /v1/convert/json-to-yaml |
Direkte Abbildung in menschenlesbares YAML im Block-Stil, wobei Key-Reihenfolge und Unicode erhalten bleiben. |
| YAML zu JSON | POST /v1/convert/yaml-to-json |
Parst .yaml- oder .yml-Dateien sicher (keine beliebige Codeausführung) zu pretty-printed JSON mit 2-Leerzeichen-Einrückung. |
| JSON zu CSV | POST /v1/convert/json-to-csv |
Konvertiert ein JSON-Array von Objekten zu kommagetrenntem CSV, wobei die Headers aus den Keys des ersten Objekts übernommen werden. |
| CSV zu JSON | POST /v1/convert/csv-to-json |
Konvertiert CSV zu einem JSON-Array, wobei die Header-Zeile zu den Keys wird und jeder Wert ein String bleibt (keine Typinferenz). |
| JSON zu TOML | POST /v1/convert/json-to-toml |
Konvertiert JSON zu TOML, wobei Arrays unter einem items-Key und Skalare unter value verpackt werden; null-Werte werden mit einem 400 abgelehnt. |
| TOML zu JSON | POST /v1/convert/toml-to-json |
Konvertiert TOML-Tabellen und -Arrays zu pretty-printed JSON und serialisiert Datetime-Werte als ISO-8601-Strings. |
| CSV zu XML | POST /v1/convert/csv-to-xml |
Konvertiert CSV zu XML, wobei Spalten-Header zu Element-Tag-Namen werden und jede Zeile als <item> innerhalb von <root> erscheint. |
| XML zu CSV | POST /v1/convert/xml-to-csv |
Flacht tabellarisches XML (wiederholte Sibling-Elemente mit konsistenten Feldern) zu kommagetrennten CSV-Zeilen ab. |
| Markdown zu HTML | POST /v1/convert/markdown-to-html |
Rendert .md- oder .markdown-Dateien zu einer vollständigen, eigenständigen HTML-Seite mit eingebettetem CSS, Tabellen, Code-Blöcken, TOC-Unterstützung und Dark Mode. |
Gemeinsame Konventionen#
- Authentifizierung: Jeder Endpunkt akzeptiert entweder einen privaten API-Schlüssel über den
X-API-Key-Header oder ein JWT-Authorization: Bearer-Token, das von einem öffentlichen Schlüssel stammt. Siehe Authentifizierung. - Request-Struktur: Alle Konvertierungen sind synchrone
multipart/form-data-POSTs mit einem erforderlichenfile-Feld sowie den optionalen Parameternoutput_filenameunddirect_download. Siehe Synchrone und asynchrone Jobs. - Antworten: Standardmäßig (
direct_download=true) wird die konvertierte Datei als rohe Bytes zurückgegeben; mitdirect_download=falseerhältst du JSON-Metadaten mitpresigned_url,object_key,filename,file_sizeundconversion_time_seconds. - Eingabeanforderungen: Alle Eingaben müssen UTF-8-kodiert sein und der erwarteten Dateiendung entsprechen; die maximale Dateigröße ist planabhängig (Founding-Plan: 5 MB).
- Fehler: Ungültige Dateien oder fehlgeschlagene Konvertierungen liefern
400, fehlende oder ungültige Zugangsdaten401, überschrittene Planlimits402und zu große Dateien413. Siehe Fehlercodes.
Häufig gestellte Fragen#
Wie authentifiziere ich Anfragen an die Datenformat-Konvertierungs-Endpunkte?#
Alle elf Endpunkte akzeptieren entweder einen privaten API-Schlüssel im X-API-Key-Header oder ein JWT-Authorization: Bearer-Token, das von einem öffentlichen Schlüssel stammt. Dieselben Zugangsdaten funktionieren bei jeder Konvertierung. Details siehe Authentifizierung.
Kann ich eine Download-URL statt der konvertierten Datei-Bytes erhalten?#
Ja. Jeder Endpunkt gibt die konvertierte Datei standardmäßig als rohe Bytes zurück; setze direct_download=false, um stattdessen JSON-Metadaten mit presigned_url, object_key, filename, file_size und conversion_time_seconds zu erhalten.
Welche Datei- und Eingabegrößenlimits gelten für Datenformat-Konvertierungen?#
Die maximale Dateigröße ist planabhängig (Founding-Plan: 5 MB); Dateien, die das Limit deines Plans überschreiten, liefern 413 Payload Too Large. Alle Eingaben müssen UTF-8-kodiert sein, und auch die monatlichen Konvertierungszahlen sind planabhängig. Bei Überschreitung wird 402 Payment Required zurückgegeben.