Documentation de l'API

Introduction

L'API de traduction traduit du texte, du HTML et du JSON structuré dans jusqu'à 24 langues officielles de l'UE. Les requêtes et réponses sont en JSON (UTF-8). Chaque requête choisit un niveau de qualité : basic (IA), pro (IA avec imposition de terminologie) ou review (vérification par échantillonnage native supplémentaire, asynchrone).

Pour essayer, utilisez la clé sandbox publique depuis votre espace client – elle se comporte comme la production mais est limitée à un quota de test. Vous obtenez des clés de production après une brève activation via votre compte client.

Clé de sandbox publiquebd_test_sandbox_2026

Authentification

Chaque requête porte votre clé API dans l'en-tête Authorization en tant que jeton Bearer. Les clés commencent par bd_test_ (sandbox) ou bd_live_ (production). Traitez les clés comme des mots de passe : jamais dans le code front-end, jamais dans le dépôt – en cas de compromission suspectée, révoquez et régénérez depuis l'espace client.

Les requêtes sans clé valide reçoivent une réponse 401. Une clé peut à tout moment être dotée d'un quota mensuel en mots ; une fois atteint, l'API répond avec le statut 402 jusqu'à ce que vous augmentiez le quota.

Authorization: Bearer bd_live_ihr_schluessel

Traduire du texte

POST/api/v1/translate

L'endpoint central traduit un ou plusieurs textes dans une langue cible. Le champ format contrôle le traitement : text (par défaut), html (le balisage est conservé) ou json (seules les valeurs de chaîne sont traduites, les clés et la structure restent inchangées).

La réponse contient les traductions dans l'ordre d'entrée, les mots source comptés et les coûts calculés en centimes. Avec l'en-tête optionnel Idempotency-Key, vous évitez le double traitement lors des répétitions réseau : des clés identiques renvoient la première réponse enregistrée.

curl https://www.baduno.com/api/v1/translate \
  -H "Authorization: Bearer bd_test_sandbox_2026" \
  -H "Content-Type: application/json" \
  -d '{
    "target": "fr",
    "texts": ["Kostenloser Versand ab 50 Euro."],
    "format": "text",
    "tier": "basic"
  }'

{
  "ok": true,
  "target": "fr",
  "tier": "basic",
  "translations": ["Livraison gratuite à partir de 50 euros."],
  "words": 6,
  "cost_cents": 12,
  "detected_source": "de"
}

Paramètre

const res = await fetch("https://www.baduno.com/api/v1/translate", {
  method: "POST",
  headers: {
    "Authorization": "Bearer " + process.env.BADUNO_API_KEY,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({ target: "it", texts: [title, description], format: "html" })
});
const { translations } = await res.json();

import os, requests

r = requests.post(
    "https://www.baduno.com/api/v1/translate",
    headers={"Authorization": f"Bearer {os.environ['BADUNO_API_KEY']}"},
    json={"target": "pl", "texts": ["Zurück zur Startseite"], "tier": "pro"},
    timeout=30,
)
r.raise_for_status()
print(r.json()["translations"][0])

$ch = curl_init("https://www.baduno.com/api/v1/translate");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer " . getenv("BADUNO_API_KEY"),
    "Content-Type: application/json"
  ],
  CURLOPT_POSTFIELDS => json_encode(["target" => "es", "texts" => [$text]])
]);
$out = json_decode(curl_exec($ch), true);

Batch & Webhooks

POST/api/v1/batches

Pour les grands volumes ou le niveau de révision, travaillez de manière asynchrone : le point de terminaison Batch accepte jusqu'à 1 000 textes et répond immédiatement avec un ID de tâche. Une fois la tâche terminée – en cas de révision après l'échantillon de langue maternelle – l'API appelle votre URL de webhook configurée avec le résultat.

Les appels webhook sont signés avec un en-tête HMAC-SHA-256 que vous vérifiez avec votre secret de webhook. Si votre serveur ne répond pas par un statut 2xx, la livraison est répétée jusqu'à cinq fois avec un intervalle croissant ; les tâches restent accessibles pendant 30 jours supplémentaires via GET.

POST /api/v1/batches            → { "ok": true, "job": "job_8f2…", "status": "processing" }
GET  /api/v1/batches/job_8f2…   → { "ok": true, "status": "done", "results": [ … ] }

Glossaires

POST/api/v1/glossaries

Les glossaires garantissent votre terminologie : chaque entrée associe un terme source à sa traduction contraignante par langue cible. Importez-les au format CSV depuis l'espace client ou via l'API ; les niveaux pro et review imposent les correspondances, tandis que basic les traite comme de simples recommandations.

Chaque compte peut contenir jusqu'à 20 glossaires, chacun avec 5 000 entrées. Les modifications prennent effet immédiatement sur toutes les demandes ultérieures – versionnez donc vos glossaires comme du code et testez d'abord les changements avec la clé sandbox.

Langues

GET/api/v1/languages

L'endpoint Langues fournit la liste actuelle des langues cibles et sources avec leur code ISO et leur nom autochtone. Utilisez-le au lieu d'une liste figée – les nouvelles langues y apparaissent automatiquement.

Consommation

GET/api/v1/usage

Le point de terminaison de consommation affiche, par clé, les mots traduits et les coûts encourus du mois en cours ainsi que la limite mensuelle définie. Vous retrouvez ces mêmes chiffres sous forme graphique dans l'espace client sous « API & Consommation ».

Codes d'erreur

Les erreurs sont renvoyées au format JSON avec les champs error (code lisible par machine) et message (description). Traitez au moins ces cas :

Limites et équité

Par défaut, 60 requêtes par minute et par clé, ainsi que 30 000 caractères par requête ; la clé sandbox est en outre limitée au quota de test. Nous débloquons des limites plus élevées après un bref examen – contactez-nous avec votre cas d'utilisation.

Comptage des mots : les mots du texte source sont comptés (limites de mots Unicode), une fois par langue cible. Pour les formats html et json, seuls les nœuds de texte traduisibles ou les valeurs de chaîne sont comptés – le balisage, les clés et les variables ne coûtent rien.

Protection des données

Traitement exclusivement pour la fourniture des services sur des serveurs dans l'UE ; le contenu n'est pas utilisé pour l'entraînement des modèles et est supprimé des journaux de traitement après 30 jours. Pour une utilisation en production, nous concluons un contrat de traitement des données conformément à l'art. 28 RGPD – détails dans le Trust Center.

N'envoyez pas de données réelles à caractère personnel via le sandbox. Pseudonymisez les contenus de test ou utilisez des exemples synthétiques.

Journal des modifications

Juillet 2026

Lancement du sandbox public : points de terminaison de traduction, de lot, de glossaire, de langues et de consommation.

Prévu

Gestion autonome des clés de production, profils de style par marque, mémoire de traduction (Translation Memory) par compte.

L'API est versionnée sous /v1 ; les extensions rétrocompatibles (nouveaux champs optionnels, nouvelles langues) se font sans changement de version. Les modifications cassantes apparaissent comme une nouvelle version avec une période de fonctionnement parallèle d'au moins douze mois.