API de conversion de formats de données#
Les endpoints Formats de données convertissent des fichiers de données structurées entre JSON, XML, YAML, CSV et TOML, et génèrent aussi du Markdown vers du HTML entièrement stylisé. Chaque conversion est une simple requête POST avec un envoi de fichier multipart/form-data : envoyez votre fichier, récupérez le résultat converti sous forme d'octets bruts, ou demandez à la place une URL de téléchargement présignée. Les onze endpoints suivent la même structure de requête, la même authentification et le même modèle d'erreurs, si bien qu'intégrer un deuxième format après le premier prend quelques minutes.
Conversions prises en charge#
| Conversion | Endpoint | Description |
|---|---|---|
| JSON vers XML | POST /v1/convert/json-to-xml |
Convertit du JSON en XML avec les objets comme enfants de <root>, les tableaux enveloppés dans des éléments <item>, et les scalaires dans <value>. |
| XML vers JSON | POST /v1/convert/xml-to-json |
Convertit du XML en JSON, en mappant les attributs vers des clés préfixées par @, le contenu textuel vers #text, et les éléments frères répétés vers des tableaux. |
| JSON vers YAML | POST /v1/convert/json-to-yaml |
Mappage direct vers un YAML en style bloc lisible par un humain, avec l'ordre des clés et l'unicode préservés. |
| YAML vers JSON | POST /v1/convert/yaml-to-json |
Analyse en toute sécurité les fichiers .yaml ou .yml (aucune exécution de code arbitraire) en JSON formaté avec une indentation de 2 espaces. |
| JSON vers CSV | POST /v1/convert/json-to-csv |
Convertit un tableau JSON d'objets en CSV délimité par des virgules, avec des en-têtes tirés des clés du premier objet. |
| CSV vers JSON | POST /v1/convert/csv-to-json |
Convertit du CSV en un tableau JSON où la ligne d'en-tête devient les clés et chaque valeur reste une chaîne de caractères (aucune inférence de type). |
| JSON vers TOML | POST /v1/convert/json-to-toml |
Convertit du JSON en TOML, en enveloppant les tableaux sous une clé items et les scalaires sous value ; les valeurs null sont rejetées avec un 400. |
| TOML vers JSON | POST /v1/convert/toml-to-json |
Convertit les tables et tableaux TOML en JSON formaté, en sérialisant les valeurs datetime sous forme de chaînes ISO-8601. |
| CSV vers XML | POST /v1/convert/csv-to-xml |
Convertit du CSV en XML avec les en-têtes de colonnes comme noms de balises d'éléments et chaque ligne comme un <item> à l'intérieur de <root>. |
| XML vers CSV | POST /v1/convert/xml-to-csv |
Aplatit du XML tabulaire (éléments frères répétés avec des champs cohérents) en lignes CSV délimitées par des virgules. |
| Markdown vers HTML | POST /v1/convert/markdown-to-html |
Génère à partir des fichiers .md ou .markdown une page HTML complète et autonome avec du CSS intégré, des tableaux, des blocs de code, la prise en charge d'une table des matières (TOC), et le mode sombre. |
Conventions communes#
- Authentification : Chaque endpoint accepte soit une clé API privée via l'en-tête
X-API-Key, soit un jeton JWTAuthorization: Bearerobtenu à partir d'une clé publique. Voir Authentification. - Forme de la requête : Toutes les conversions sont des POST
multipart/form-datasynchrones avec un champfileobligatoire, plus les paramètres optionnelsoutput_filenameetdirect_download. Voir Tâches synchrones et asynchrones. - Réponses : Par défaut (
direct_download=true), le fichier converti est renvoyé sous forme d'octets bruts ; avecdirect_download=false, vous recevez des métadonnées JSON contenantpresigned_url,object_key,filename,file_sizeetconversion_time_seconds. - Exigences sur l'entrée : Toutes les entrées doivent être encodées en UTF-8 et correspondre à l'extension de fichier attendue ; la taille de fichier maximale dépend du forfait (forfait Founding : 5 MB).
- Erreurs : Les fichiers invalides ou les conversions échouées renvoient
400, des identifiants manquants ou invalides401, un dépassement des limites du forfait402, et des fichiers trop volumineux413. Voir Codes d'erreur.
Questions fréquentes#
Comment authentifier les requêtes vers les endpoints de conversion de formats de données ?#
Les onze endpoints acceptent soit une clé API privée dans l'en-tête X-API-Key, soit un jeton JWT Authorization: Bearer obtenu à partir d'une clé publique. Les mêmes identifiants fonctionnent pour toutes les conversions. Voir Authentification pour plus de détails.
Puis-je obtenir une URL de téléchargement au lieu des octets du fichier converti ?#
Oui. Chaque endpoint renvoie par défaut le fichier converti sous forme d'octets bruts ; définissez direct_download=false pour recevoir à la place des métadonnées JSON avec presigned_url, object_key, filename, file_size et conversion_time_seconds.
Quelles limites de taille de fichier et d'entrée s'appliquent aux conversions de formats de données ?#
La taille de fichier maximale dépend du forfait (forfait Founding : 5 MB), et les fichiers dépassant la limite de votre forfait renvoient 413 Payload Too Large. Toutes les entrées doivent être encodées en UTF-8, et le nombre de conversions mensuelles dépend également du forfait. Le dépasser renvoie 402 Payment Required.