API-documentatie

Inleiding

De Translation API vertaalt tekst, HTML en gestructureerde JSON naar maximaal 24 EU-officiële talen. Verzoeken en antwoorden zijn JSON (UTF-8). Elk verzoek kiest een kwaliteitsniveau: basis (AI), pro (AI met terminologiedwang) of review (extra steekproefcontrole door moedertaalsprekers, asynchroon).

Om uit te proberen gebruikt u de openbare sandbox-sleutel uit het klantportaal – deze gedraagt zich zoals de productie, maar is beperkt tot een testquotum. Productiesleutels ontvangt u na een korte activering via uw klantaccount.

Publieke sandbox-sleutelbd_test_sandbox_2026

Authenticatie

Elk verzoek bevat uw API-sleutel in de Authorization-header als Bearer-token. Sleutels beginnen met bd_test_ (sandbox) of bd_live_ (productie). Behandel sleutels als wachtwoorden: nooit in frontend-code, nooit in de repository – bij vermoeden van compromittering intrekken en opnieuw genereren in het klantportaal.

Verzoeken zonder geldige sleutel beantwoordt de API met status 401. Een sleutel kan te allen tijde worden voorzien van een maandlimiet in woorden; bij bereiking antwoordt de API met status 402, totdat u het limiet verhoogt.

Authorization: Bearer bd_live_ihr_schluessel

Tekst vertalen

POST/api/v1/translate

Het centrale eindpunt vertaalt een of meer teksten naar een doeltaal. Het veld format bepaalt de behandeling: text (standaard), html (opmaak blijft behouden) of json (alleen tekenreekswaarden worden vertaald, sleutels en structuur blijven ongewijzigd).

Het antwoord bevat de vertalingen in invoervolgorde, de getelde bronwoorden en de berekende kosten in cent. Met de optionele header Idempotency-Key voorkomt u dubbele verwerking bij netwerkherhalingen: identieke sleutels leveren het opgeslagen eerste antwoord.

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

Voor grote hoeveelheden of de reviewfase werkt u asynchroon: het batch-eindpunt accepteert tot 1.000 teksten en reageert direct met een job-ID. Zodra de job is voltooid – bij review na de moedertaalsteekproef – roept de API uw opgeslagen webhook-URL aan met het resultaat.

Webhook-aanroepen zijn ondertekend met een HMAC-SHA-256-header, die u verifieert met uw webhook-geheim. Als uw server niet reageert met status 2xx, wordt de bezorging tot vijf keer herhaald met oplopende tussenpozen; jobs blijven daarnaast 30 dagen oproepbaar via GET.

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

Glossaria

POST/api/v1/glossaries

Glossaria beveiligen uw terminologie: per item een brontaalterm en zijn bindende vertaling per doeltaal. Upload als CSV in het klantportaal of via API; de niveaus pro en review passen treffers bindend toe, basic gebruikt ze als aanbeveling.

Per account zijn maximaal 20 glossaria met elk 5.000 items mogelijk. Wijzigingen zijn direct van invloed op alle volgende aanvragen – versioneer glossaria daarom zoals code en test wijzigingen eerst met de sandbox-sleutel.

Talen

GET/api/v1/languages

Het talen-eindpunt levert de momenteel beschikbare doel- en brontalen met ISO-code en eigen benaming. Gebruik het in plaats van een vaste lijst – nieuwe talen verschijnen daar automatisch.

Verbruik

GET/api/v1/usage

Het verbruikseindpunt toont per sleutel de vertaalde woorden en gemaakte kosten van de lopende maand, evenals het ingestelde maandelijkse limiet. Dezelfde cijfers ziet u grafisch in het klantengedeelte onder 'API & Verbruik'.

Foutcodes

Fouten worden weergegeven als JSON met de velden error (machineleesbare code) en message (beschrijving). Behandel ten minste deze gevallen:

Limieten & eerlijkheid

Standaard gelden 60 verzoeken per minuut en sleutel, en 30.000 tekens per verzoek; de sandbox-sleutel is bovendien beperkt tot het testquotum. Hogere limieten stellen we na een korte controle beschikbaar – meld u met uw gebruikssituatie.

Woordtelling: Er worden woorden van de brontekst geteld (Unicode-woordgrenzen), per doeltaal eenmaal. Bij de formaten html en json tellen alleen vertaalbare tekstknooppunten of stringwaarden – markup, sleutels en variabelen zijn gratis.

Privacy

Verwerking uitsluitend voor dienstverlening op EU-servers; inhoud wordt niet gebruikt voor het trainen van modellen en wordt na 30 dagen uit de verwerkingslogboeken verwijderd. Voor productiegebruik sluiten wij een verwerkersovereenkomst conform art. 28 AVG – details in het Trust Center.

Stuur geen echte persoonsgegevens via de sandbox. Pseudonimiseer testinhoud of gebruik synthetische voorbeelden.

Wijzigingslogboek

juli 2026

Start van de openbare sandbox: vertaal-, batch-, glossarium-, taal- en verbruikseindpunt.

Gepland

Productiesleutel-zelfbeheer, stijlprofielen per merk, vertaalgeheugen (Translation Memory) per account.

De API is versiebeheerd onder /v1; achterwaarts compatibele uitbreidingen (nieuwe optionele velden, nieuwe talen) worden uitgevoerd zonder versiewijziging. Brekende wijzigingen worden als nieuwe versie uitgebracht met minimaal twaalf maanden parallel bedrijf.