API dokumentácia

Úvod

Translation API prekladá text, HTML a štruktúrovaný JSON do až 24 úradných jazykov EÚ. Požiadavky a odpovede sú vo formáte JSON (UTF-8). Každá požiadavka si volí úroveň kvality: basic (AI), pro (AI s presadením terminológie) alebo review (dodatočná kontrola vzoriek rodným hovorcom, asynchrónne).

Na vyskúšanie použite verejný sandboxový kľúč z klientskej zóny – správa sa ako produkčný, ale je obmedzený na testovaciu kvótu. Produkčný kľúč získate po krátkom aktivovaní cez svoj klientský účet.

Verejný sandbox kľúčbd_test_sandbox_2026

Autentifikácia

Každá požiadavka nesie váš API kľúč v Authorization hlavičke ako Bearer token. Kľúče začínajú na bd_test_ (sandbox) alebo bd_live_ (produkcia). S kľúčmi zaobchádzajte ako s heslami: nikdy nie v kóde frontendu, nikdy v repozitári – pri podozrení na kompromitáciu v klientskej zóne zrušte a vytvorte nový.

Požiadavky bez platného kľúča API odpovedá statusom 401. Kľúč môže byť kedykoľvek obmedzený mesačným limitom slov; po jeho dosiahnutí API odpovedá statusom 402, kým limit nezvýšite.

Authorization: Bearer bd_live_ihr_schluessel

Preklad textu

POST/api/v1/translate

Centrálny koncový bod prekladá jeden alebo viac textov do cieľového jazyka. Pole format riadi spracovanie: text (štandard), html (značky zostávajú zachované) alebo json (prekladajú sa iba reťazcové hodnoty, kľúče a štruktúra zostávajú nezmenené).

Odpoveď obsahuje preklady v poradí vstupu, spočítané zdrojové slová a vypočítané náklady v centoch. Pomocou voliteľnej hlavičky Idempotency-Key zabránite dvojitému spracovaniu pri opakovaniach siete: identické kľúče vrátia uloženú prvú odpoveď.

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

Dávky a Webhooky

POST/api/v1/batches

Pre veľké objemy alebo fázu kontroly pracujte asynchrónne: Batch koncový bod prijíma až 1 000 textov a ihneď vráti ID úlohy. Keď je úloha dokončená – pri kontrole po vzorke od rodeného hovorcu – API zavolá vašu zaregistrovanú webhook URL s výsledkom.

Webhook volania sú podpísané hlavičkou HMAC-SHA-256, ktorú overíte svojím webhook tajomstvom. Ak váš server neodpovedá stavom 2xx, doručenie sa opakuje až päťkrát s rastúcim odstupom; úlohy sú navyše 30 dní načítateľné pomocou GET.

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

Glosáre

POST/api/v1/glossaries

Glosáre zabezpečujú vašu terminológiu: každý záznam obsahuje zdrojový pojem a jeho záväzný preklad pre každý cieľový jazyk. Nahráva sa ako CSV v zákazníckej sekcii alebo cez API; úrovne pro a review presadzujú zhody záväzne, basic ich používa ako odporúčanie.

Na účet je možné až 20 glosárov s maximálne 5.000 záznamami každý. Zmeny sa prejavia okamžite na všetky nasledujúce požiadavky – verzujte preto glosáre ako kód a zmeny najskôr otestujte pomocou sandbox kľúča.

Jazyky

GET/api/v1/languages

Koncový bod jazykov poskytuje aktuálne dostupné cieľové a zdrojové jazyky s ISO kódom a vlastným názvom. Používajte ho namiesto pevne zapojenej listy – nové jazyky sa tam automaticky objavujú.

Spotreba

GET/api/v1/usage

Koncový bod spotreby zobrazuje pre každý kľúč preložené slová a vzniknuté náklady aktuálneho mesiaca, ako aj nastavený mesačný limit. Rovnaké čísla vidíte graficky v zákazníckej časti v časti „API a spotreba“.

Chybové kódy

Chyby prichádzajú ako JSON s poľami error (strojovo čitateľný kód) a message (popis). Ošetrite aspoň tieto prípady:

Obmedzenia a férovosť

Štandardne platí 60 požiadaviek za minútu na kľúč a 30 000 znakov na požiadavku; sandboxový kľúč je navyše obmedzený na testovaciu kvótu. Vyššie limity uvoľníme po krátkom overení – kontaktujte nás so svojím prípadom použitia.

Počítanie slov: Počítajú sa slová zdrojového textu (hranice slov podľa Unicode), raz pre každý cieľový jazyk. Pri formátoch html a json sa počítajú iba preložiteľné textové uzly alebo reťazcové hodnoty – značky, kľúče a premenné sú bezplatné.

Ochrana údajov

Spracovanie výlučne na účely poskytovania služieb na serveroch v EÚ; obsah sa nepoužíva na trénovanie modelov a po 30 dňoch sa vymaže z protokolov spracovania. Pre produkčné použitie uzatvárame zmluvu o spracovaní údajov podľa čl. 28 GDPR – podrobnosti v Trust Center.

Nezasielajte prostredníctvom sandboxu žiadne skutočné osobné údaje. Pseudonymizujte testovací obsah alebo použite syntetické príklady.

Záznam zmien

Júl 2026

Spustenie verejnej sandboxu: prekladový, dávkový, glosárový, jazykový a spotrebný koncový bod.

Plánované

Samospráva produkčných kľúčov, profily štýlov podľa značky, pamäť prekladov (Translation Memory) podľa účtu.

API je verzovaná pod /v1; spätne kompatibilné rozšírenia (nové voliteľné polia, nové jazyky) sa vykonávajú bez zmeny verzie. Zásadné zmeny sa objavia ako nová verzia s minimálne dvanástimi mesiacmi súbežnej prevádzky.