API-dokumentation

Introduktion

Översättnings-API:et översätter text, HTML och strukturerad JSON till upp till 24 EU-officiella språk. Förfrågningar och svar är JSON (UTF-8). Varje förfrågan väljer en kvalitetsnivå: basic (AI), pro (AI med terminologitillämpning) eller review (ytterligare stickprovskontroll av modersmålstalare, asynkront).

För att prova använder du den offentliga sandlådenyckeln från kundområdet – den fungerar som produktion men är begränsad till en testkvot. Produktionsnycklar får du efter kort aktivering via ditt kundkonto.

Offentlig sandbox-nyckelbd_test_sandbox_2026

Autentisering

Varje förfrågan bär din API-nyckel i Authorization-headern som Bearer-token. Nycklar börjar med bd_test_ (sandlåda) eller bd_live_ (produktion). Hantera nycklar som lösenord: aldrig i frontend-kod, aldrig i repository – vid misstanke om kompromettering, återkalla och återskapa i kundområdet.

Förfrågningar utan giltig nyckel besvaras av API:et med status 401. En nyckel kan när som helst förses med en månadsgräns i ord; när gränsen nås svarar API:et med status 402 tills du höjer gränsen.

Authorization: Bearer bd_live_ihr_schluessel

Översätt text

POST/api/v1/translate

Den centrala slutpunkten översätter en eller flera texter till ett målspråk. Fältet format styr behandlingen: text (standard), html (markup bevaras) eller json (endast strängvärden översätts, nycklar och struktur förblir oförändrade).

Svaret innehåller översättningarna i inmatningsordning, de räknade källorden och de beräknade kostnaderna i cent. Med den valfria headern Idempotency-Key förhindrar du dubbelbearbetning vid nätverksförsök: identiska nycklar ger det lagrade första svaret.

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 och webhooks

POST/api/v1/batches

För stora mängder eller granskningssteget arbetar du asynkront: Batch-slutpunkten tar emot upp till 1 000 texter och svarar omedelbart med ett jobb-ID. Så snart jobbet är slutfört – vid granskning efter det modersmålsspråkiga stickprovet – anropar API:et din angivna webhook-URL med resultatet.

Webhook-anrop är signerade med en HMAC-SHA-256-header som du verifierar med din webhook-hemlighet. Om din server inte svarar med status 2xx, kommer leveransen att upprepas upp till fem gånger med ökande intervall; jobb är dessutom tillgängliga för hämtning via GET i 30 dagar.

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

Ordlistor

POST/api/v1/glossaries

Ordlistor säkrar er terminologi: per post en källterm och dess bindande översättning per målspråk. Laddas upp som CSV i kundområdet eller via API; nivån pro och review gör träffar bindande, basic använder dem som rekommendation.

Per konto är upp till 20 ordlistor med vardera 5 000 poster möjliga. Ändringar påverkar omedelbart alla efterföljande förfrågningar – versionshantera därför ordlistorna som kod och testa ändringarna först med sandbox-nyckeln.

Språk

GET/api/v1/languages

Språkändpunkten levererar de aktuellt tillgängliga mål- och källspråken med ISO-kod och egenbeteckning. Använd den istället för en fast inkopplad lista – nya språk visas där automatiskt.

Förbrukning

GET/api/v1/usage

Förbrukningsslutpunkten visar per nyckel de översatta orden och uppkomna kostnaderna för den aktuella månaden samt den inställda månadsgränsen. Samma siffror ser du grafiskt i kundområdet under "API & förbrukning".

Felkoder

Fel kommer som JSON med fälten error (maskinläsbar kod) och message (beskrivning). Hantera åtminstone dessa fall:

Gränser & Rättvisa

Som standard gäller 60 förfrågningar per minut och nyckel samt 30 000 tecken per förfrågan; sandlådenyckeln är dessutom begränsad till testkvoten. Högre gränser aktiverar vi efter en kort granskning – kontakta oss med ditt användningsfall.

Ordräkning: Räkning av ord i källtexten (Unicode-ordgränser), en gång per målspråk. För format html och json räknas endast översättbara textnoder respektive strängvärden – markup, nycklar och variabler kostar inget.

Dataskydd

Behandling uteslutande för tjänsteleverans på EU-servrar; innehåll används inte för träning av modeller och raderas efter 30 dagar från behandlingsloggarna. För produktionsanvändning ingår vi ett personuppgiftsbiträdesavtal enligt art. 28 GDPR – detaljer i Trust Center.

Skicka inga verkliga personuppgifter via sandlådan. Pseudonymisera testinnehåll eller använd syntetiska exempel.

Ändringsprotokoll

juli 2026

Start av den offentliga sandlådan: översättnings-, batch-, ordlista-, språk- och förbrukningsslutpunkt.

Planerad

Självadministration av produktionsnycklar, stilprofiler per varumärke, översättningsminne (Translation Memory) per konto.

API:n är versionerad under /v1; bakåtkompatibla utökningar (nya valfria fält, nya språk) görs utan versionsväxling. Brytande ändringar visas som ny version med minst tolv månaders parallell drift.