API-Dokumentation

Einführung

Die Translation API übersetzt Text, HTML und strukturiertes JSON in bis zu 24 EU-Amtssprachen. Anfragen und Antworten sind JSON (UTF-8). Jede Anfrage wählt eine Qualitätsstufe: basic (KI), pro (KI mit Terminologie-Durchsetzung) oder review (zusätzlich muttersprachliche Stichprobenprüfung, asynchron).

Zum Ausprobieren nutzen Sie den öffentlichen Sandbox-Schlüssel aus dem Kundenbereich – er verhält sich wie die Produktion, ist aber auf ein Testkontingent begrenzt. Produktivschlüssel erhalten Sie nach kurzer Freischaltung über Ihr Kundenkonto.

Öffentlicher Sandbox-Schlüsselbd_test_sandbox_2026

Authentifizierung

Jede Anfrage trägt Ihren API-Schlüssel im Authorization-Header als Bearer-Token. Schlüssel beginnen mit bd_test_ (Sandbox) oder bd_live_ (Produktion). Behandeln Sie Schlüssel wie Passwörter: nie im Frontend-Code, nie im Repository – bei Verdacht auf Kompromittierung im Kundenbereich widerrufen und neu erzeugen.

Anfragen ohne gültigen Schlüssel beantwortet die API mit Status 401. Ein Schlüssel kann jederzeit mit einem Monatslimit in Wörtern versehen werden; bei Erreichen antwortet die API mit Status 402, bis Sie das Limit anheben.

Authorization: Bearer bd_live_ihr_schluessel

Text übersetzen

POST/api/v1/translate

Der zentrale Endpunkt übersetzt einen oder mehrere Texte in eine Zielsprache. Das Feld format steuert die Behandlung: text (Standard), html (Markup bleibt erhalten) oder json (nur String-Werte werden übersetzt, Schlüssel und Struktur bleiben unverändert).

Die Antwort enthält die Übersetzungen in Eingabereihenfolge, die gezählten Quellwörter und die berechneten Kosten in Cent. Mit dem optionalen Header Idempotency-Key verhindern Sie Doppelverarbeitung bei Netzwerk-Wiederholungen: identische Schlüssel liefern die gespeicherte Erstantwort.

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"
}

Parameter

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

Für große Mengen oder die Review-Stufe arbeiten Sie asynchron: Der Batch-Endpunkt nimmt bis zu 1.000 Texte an und antwortet sofort mit einer Job-ID. Sobald der Job abgeschlossen ist – bei review nach der muttersprachlichen Stichprobe – ruft die API Ihre hinterlegte Webhook-URL mit dem Ergebnis auf.

Webhook-Aufrufe sind mit einem HMAC-SHA-256-Header signiert, den Sie mit Ihrem Webhook-Geheimnis prüfen. Antwortet Ihr Server nicht mit Status 2xx, wird die Zustellung bis zu fünfmal mit wachsendem Abstand wiederholt; Jobs bleiben zusätzlich 30 Tage per GET abrufbar.

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

Glossare

POST/api/v1/glossaries

Glossare sichern Ihre Terminologie: je Eintrag ein Quellbegriff und seine verbindliche Übersetzung je Zielsprache. Hochgeladen wird als CSV im Kundenbereich oder per API; die Stufe pro und review setzen Treffer verbindlich durch, basic nutzt sie als Empfehlung.

Je Konto sind bis zu 20 Glossare mit je 5.000 Einträgen möglich. Änderungen wirken sofort auf alle folgenden Anfragen – versionieren Sie Glossare daher wie Code und testen Sie Änderungen zuerst mit dem Sandbox-Schlüssel.

Sprachen

GET/api/v1/languages

Der Sprachen-Endpunkt liefert die aktuell verfügbaren Ziel- und Quellsprachen mit ISO-Code und Eigenbezeichnung. Verwenden Sie ihn statt einer fest verdrahteten Liste – neue Sprachen erscheinen dort automatisch.

Verbrauch

GET/api/v1/usage

Der Verbrauchs-Endpunkt zeigt je Schlüssel die übersetzten Wörter und angefallenen Kosten des laufenden Monats sowie das gesetzte Monatslimit. Dieselben Zahlen sehen Sie grafisch im Kundenbereich unter „API & Verbrauch“.

Fehlercodes

Fehler kommen als JSON mit den Feldern error (maschinenlesbarer Code) und message (Beschreibung). Behandeln Sie mindestens diese Fälle:

Limits & Fairness

Standardmäßig gelten 60 Anfragen pro Minute und Schlüssel sowie 30.000 Zeichen je Anfrage; der Sandbox-Schlüssel ist zusätzlich auf das Testkontingent begrenzt. Höhere Limits schalten wir nach kurzer Prüfung frei – melden Sie sich mit Ihrem Anwendungsfall.

Wortzählung: Gezählt werden Wörter des Quelltexts (Unicode-Wortgrenzen), je Zielsprache einmal. Bei format html und json zählen nur übersetzbare Textknoten bzw. String-Werte – Markup, Schlüssel und Variablen kosten nichts.

Datenschutz

Verarbeitung ausschließlich zur Leistungserbringung auf EU-Servern; Inhalte werden nicht zum Training von Modellen verwendet und nach 30 Tagen aus den Verarbeitungsprotokollen gelöscht. Für die Produktionsnutzung schließen wir einen Auftragsverarbeitungsvertrag nach Art. 28 DSGVO – Details im Trust Center.

Senden Sie über die Sandbox keine personenbezogenen Echtdaten. Pseudonymisieren Sie Testinhalte oder nutzen Sie synthetische Beispiele.

Änderungsprotokoll

Juli 2026

Start der öffentlichen Sandbox: Übersetzungs-, Batch-, Glossar-, Sprachen- und Verbrauchs-Endpunkt.

Geplant

Produktivschlüssel-Selbstverwaltung, Stilprofile je Marke, Übersetzungsspeicher (Translation Memory) je Konto.

Die API ist unter /v1 versioniert; rückwärtskompatible Erweiterungen (neue optionale Felder, neue Sprachen) erfolgen ohne Versionswechsel. Brechende Änderungen erscheinen als neue Version mit mindestens zwölf Monaten Parallelbetrieb.