API dokumentacija

Uvod

Translation API prevodi tekst, HTML i strukturirani JSON na do 24 službena jezika EU-a. Zahtjevi i odgovori su u JSON formatu (UTF-8). Svaki zahtjev odabire razinu kvalitete: basic (AI), pro (AI s terminološkom primjenom) ili review (dodatna provjera uzorka od strane izvornog govornika, asinkrono).

Za testiranje koristite javni sandbox ključ iz korisničkog područja – ponaša se kao produkcija, ali je ograničen na testnu kvotu. Produkcijski ključ dobivate nakon kratke aktivacije putem korisničkog računa.

Javni sandbox ključbd_test_sandbox_2026

Autentifikacija

Svaki zahtjev nosi vaš API ključ u Authorization zaglavlju kao Bearer token. Ključevi počinju s bd_test_ (sandbox) ili bd_live_ (produkcija). Ključeve tretirajte kao lozinke: nikada u frontend kodu, nikada u repozitoriju – ako sumnjate na kompromitaciju, opozovite ih u korisničkom području i kreirajte nove.

Zahtjeve bez valjanog ključa API odgovara statusom 401. Ključ se u svakom trenutku može ograničiti mjesečnim limitom u riječima; kada se dosegne, API odgovara statusom 402 sve dok ne podignete limit.

Authorization: Bearer bd_live_ihr_schluessel

Prijevod teksta

POST/api/v1/translate

Središnja krajnja točka prevodi jedan ili više tekstova na ciljani jezik. Polje format upravlja načinom obrade: text (zadano), html (oznake ostaju nepromijenjene) ili json (samo se vrijednosti nizova prevode, ključevi i struktura ostaju nepromijenjeni).

Odgovor sadrži prijevode u redoslijedu unosa, prebrojane izvorne riječi i izračunate troškove u centima. Uz opcionalno zaglavlje Idempotency-Key sprječavate dvostruku obradu kod ponavljanja u mreži: identični ključevi vraćaju spremljeni 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"
}

Parametar

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 i webhookovi

POST/api/v1/batches

Za velike količine ili fazu pregleda radite asinkrono: Batch krajnja točka prima do 1.000 tekstova i odmah odgovara ID-om posla. Čim je posao dovršen – kod pregleda nakon uzorka na izvornom jeziku – API poziva vašu pohranjenu Webhook URL s rezultatom.

Webhook pozivi potpisani su HMAC-SHA-256 zaglavljem koje provjeravate svojom Webhook tajnom. Ako vaš poslužitelj ne odgovori s statusom 2xx, isporuka se ponavlja do pet puta s rastućim razmakom; poslovi ostaju dostupni putem GET-a dodatnih 30 dana.

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

Glosari

POST/api/v1/glossaries

Glosari jamče dosljednost terminologije: svaki unos sadrži izvorni pojam i njegov obvezujući prijevod za ciljni jezik. Učitavanje se vrši putem CSV datoteke u korisničkom području ili API-jem; stupanj pro i review primjenjuju pogotke kao obvezne, dok ih basic koristi kao preporuku.

Po računu moguće je do 20 glosara s po 5.000 unosa. Izmjene stupaju na snagu odmah za sve sljedeće zahtjeve – stoga verzionirajte glosare poput koda i prvo testirajte izmjene pomoću sandbox ključa.

Jezici

GET/api/v1/languages

Krajnja točka za jezike isporučuje trenutno dostupne ciljne i izvorne jezike s ISO kodom i nazivom na izvornom jeziku. Koristite je umjesto tvrdo kodiranog popisa – novi jezici se ondje automatski pojavljuju.

Potrošnja

GET/api/v1/usage

Krajnja točka potrošnje prikazuje po ključu prevedene riječi i nastale troškove tekućeg mjeseca, kao i postavljeno mjesečno ograničenje. Iste brojke vidite grafički u korisničkom području pod „API i potrošnja“.

Kodovi pogrešaka

Pogreške dolaze kao JSON s poljima error (strojno čitljiv kod) i message (opis). Obradite barem ove slučajeve:

Ograničenja & poštenje

Standardno vrijede 60 zahtjeva po minuti po ključu te 30.000 znakova po zahtjevu; sandbox ključ je dodatno ograničen na testni kontingent. Viša ograničenja aktiviramo nakon kratke provjere – javite se s vašim slučajem uporabe.

Brojanje riječi: Broje se riječi izvornog teksta (Unicode granice riječi), jednom po ciljnom jeziku. Kod formata html i json broje se samo prevedivi tekstualni čvorovi ili vrijednosti nizova – oznake, ključevi i varijable ne koštaju.

Privatnost

Obrada isključivo za pružanje usluga na poslužiteljima u EU; sadržaj se ne koristi za treniranje modela i briše se iz zapisa obrade nakon 30 dana. Za produkcijsku upotrebu sklapamo ugovor o obradi podataka prema čl. 28. GDPR-a – detalji u Trust Centru.

Ne šaljite stvarne osobne podatke putem Sandboxa. Pseudonimizirajte testne sadržaje ili koristite sintetičke primjere.

Dnevnik promjena

Srpanj 2026.

Pokretanje javnog sandboxa: krajnje točke za prijevod, batch, rječnik, jezike i potrošnju.

Planirano

Samoupravljanje produktivnim ključevima, stilski profili po marki, prevoditeljska memorija (Translation Memory) po računu.

API je verzionirana putem /v1; proširenja koja su unatrag kompatibilna (nova opcijska polja, novi jezici) događaju se bez promjene verzije. Promjene koje narušavaju kompatibilnost pojavljuju se kao nova verzija s najmanje dvanaest mjeseci paralelnog rada.