API dokumentacija

Uvod

Translation API prevaja besedilo, HTML in strukturiran JSON v do 24 uradnih jezikov EU. Zahteve in odgovori so v formatu JSON (UTF-8). Vsaka zahteva izbere stopnjo kakovosti: basic (UI), pro (UI z uveljavljanjem terminologije) ali review (dodatno preverjanje vzorcev pri maternih govorcih, asinhrono).

Za preizkušanje uporabite javni peskovnik ključ iz uporabniškega območja – obnaša se kot produkcija, vendar je omejen na testno kvoto. Produkcijski ključ dobite po kratki aktivaciji prek vašega uporabniškega računa.

Javni ključ peskovnikabd_test_sandbox_2026

Avtentikacija

Vsaka zahteva vključuje vaš API ključ v Authorization glavi kot žeton nosilca. Ključi se začnejo z bd_test_ (peskovnik) ali bd_live_ (produkcija). Ključe obravnavajte kot gesla: nikoli v kodi frontenda, nikoli v repozitoriju – ob sumu kompromitacije v uporabniškem območju prekličite in ustvarite novega.

API na zahteve brez veljavnega ključa odgovori s statusom 401. Ključ lahko kadar koli omejite z mesečno omejitvijo v besedah; ob dosegu API odgovori s statusom 402, dokler ne povečate omejitve.

Authorization: Bearer bd_live_ihr_schluessel

Prevajanje besedila

POST/api/v1/translate

Osrednja končna točka prevede eno ali več besedil v ciljni jezik. Polje format nadzoruje obravnavo: text (privzeto), html (oznaka ostane nespremenjena) ali json (prevedejo se samo nizovne vrednosti, ključi in struktura ostanejo nespremenjeni).

Odgovor vsebuje prevode v vrstnem redu vnosa, preštete izvorne besede in izračunane stroške v centih. Z izbirnim glavo Idempotency-Key preprečite dvojno obdelavo pri omrežnih ponovitvah: enaki ključi vrnejo shranjeni prvi odgovor.

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);

Paketna obdelava in spletni kavlji

POST/api/v1/batches

Za velike količine ali raven pregleda delujete asinhrono: Končna točka Batch sprejme do 1.000 besedil in takoj odgovori z ID-jem opravila. Ko je opravilo končano – pri pregledu po vzorcu v maternem jeziku – API pokliče vaš shranjeni URL spletnega kavlja z rezultatom.

Klici spletnih kavljev so podpisani z glavo HMAC-SHA-256, ki jo preverite s svojo skrivnostjo spletnega kavlja. Če vaš strežnik ne odgovori s statusom 2xx, se dostava ponovi do petkrat z naraščajočim zamikom; opravila so poleg tega še 30 dni na voljo prek GET.

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

Glosarji

POST/api/v1/glossaries

Glosarji zavarujejo vašo terminologijo: vsak vnos vsebuje izvorni izraz in njegov obvezujoč prevod za vsak ciljni jezik. Naloži se kot CSV v uporabniškem območju ali prek API-ja; ravni pro in review zadetke obvezno upoštevata, basic jih uporablja kot priporočilo.

Na račun je mogočih do 20 glosarjev s po 5.000 vnosi. Spremembe takoj vplivajo na vsa naslednja povpraševanja – zato glosarje verzionirajte kot kodo in spremembe najprej preizkusite s ključem peskovnika.

Jeziki

GET/api/v1/languages

Končna točka za jezike zagotavlja trenutno razpoložljive ciljne in izvorne jezike z ISO-kodo in lastnim imenom. Uporabite jo namesto trdno povezanega seznama – novi jeziki se tam pojavijo samodejno.

Poraba

GET/api/v1/usage

Končna točka porabe prikazuje za vsak ključ prevedene besede in nastale stroške tekočega meseca ter nastavljeno mesečno omejitev. Iste številke vidite grafično v strankinem območju pod »API in poraba«.

Kode napak

Napake prihajajo kot JSON s poljema error (strojno berljiva koda) in message (opis). Obdelajte vsaj naslednje primere:

Omejitve in pravičnost

Privzeto velja 60 zahtevkov na minuto na ključ ter 30.000 znakov na zahtevek; ključ peskovnika je dodatno omejen na testno kvoto. Višje omejitve omogočimo po kratkem pregledu – prijavite se s svojim primerom uporabe.

Štetje besed: Štejejo se besede izvornega besedila (Unicode-ov mejnik besed), enkrat na ciljni jezik. Pri formatih html in json se štejejo samo prevodljiva vozlišča besedila oziroma vrednosti nizov – oznake, ključi in spremenljivke ne stanejo nič.

Varstvo podatkov

Obdelava izključno za izvajanje storitev na strežnikih v EU; vsebine se ne uporabljajo za usposabljanje modelov in se po 30 dneh izbrišejo iz dnevnikov obdelave. Za produkcijsko uporabo sklenemo pogodbo o obdelavi podatkov v skladu s členom 28 GDPR – podrobnosti v Trust Centru.

Prek peskovnika ne pošiljajte resničnih osebnih podatkov. Psevdonimizirajte testne vsebine ali uporabite sintetične primere.

Dnevnik sprememb

Julij 2026

Zagon javnega peskovnika: končne točke za prevajanje, paketno obdelavo, glosar, jezike in porabo.

Načrtovano

Samoupravljanje produktnih ključev, profili stilov po znamki, prevajalski spomin (Translation Memory) po računu.

API je različica /v1; povratno združljive razširitve (nova neobvezna polja, novi jeziki) se izvajajo brez spremembe različice. Prelomne spremembe se pojavijo kot nova različica z vsaj dvanajstimi meseci vzporednega delovanja.