Dokumentace API

Úvod

Translation API překládá text, HTML a strukturovaný JSON do až 24 úředních jazyků EU. Požadavky a odpovědi jsou ve formátu JSON (UTF-8). Každý požadavek volí úroveň kvality: basic (AI), pro (AI s vynucením terminologie) nebo review (navíc rodilá namátková kontrola, asynchronně).

Pro vyzkoušení použijte veřejný sandboxový klíč z klientské sekce – chová se jako produkce, ale je omezen na testovací kvótu. Produkční klíč získáte po krátkém povolení prostřednictvím vašeho klientského účtu.

Veřejný sandbox klíčbd_test_sandbox_2026

Autentizace

Každý požadavek nese váš API klíč v hlavičce Authorization jako Bearer token. Klíče začínají na bd_test_ (sandbox) nebo bd_live_ (produkce). S klíči zacházejte jako s hesly: nikdy v kódu frontendu, nikdy v repozitáři – při podezření na kompromitaci v klientské sekci odvolejte a vytvořte nový.

Požadavky bez platného klíče API odpovídá stavem 401. Klíč lze kdykoli opatřit měsíčním limitem ve slovech; po jeho dosažení API odpovídá stavem 402, dokud limit nezvýšíte.

Authorization: Bearer bd_live_ihr_schluessel

Překlad textu

POST/api/v1/translate

Centrální koncový bod překládá jeden nebo více textů do cílového jazyka. Pole format řídí zpracování: text (výchozí), html (značky zůstávají) nebo json (překládají se pouze řetězcové hodnoty, klíče a struktura zůstávají nezměněny).

Odpověď obsahuje překlady v pořadí vstupu, spočítaná zdrojová slova a vypočítané náklady v centech. Pomocí volitelné hlavičky Idempotency-Key zabráníte duplicitnímu zpracování při opakování sítě: identické klíče vrátí uloženou první odpověď.

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"
}

Parametr

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

Pro velké objemy nebo fázi review pracujte asynchronně: Dávkový endpoint přijme až 1 000 textů a okamžitě odpoví ID úlohy. Jakmile je úloha dokončena – v případě review po vzorku rodilého mluvčího – API zavolá na vaši zaregistrovanou URL webhooku s výsledkem.

Volání webhooků je podepsáno hlavičkou HMAC-SHA-256, kterou ověříte pomocí svého tajného klíče webhooku. Pokud váš server neodpoví stavem 2xx, doručování se opakuje až pětkrát s rostoucím intervalem; úlohy zůstávají navíc 30 dní přístupné přes GET.

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

Glosáře

POST/api/v1/glossaries

Glosáře zajišťují vaši terminologii: každý záznam obsahuje zdrojový pojem a jeho závazný překlad pro každý cílový jazyk. Nahrává se jako CSV v klientské sekci nebo přes API; úroveň pro a review prosazují shody závazně, basic je používá jako doporučení.

Na jeden účet je možné mít až 20 glosářů s až 5 000 záznamy každý. Změny se okamžitě projeví na všech následujících požadavcích – proto verzujte glosáře jako kód a změny nejprve otestujte pomocí sandboxového klíče.

Jazyky

GET/api/v1/languages

Koncový bod jazyků poskytuje aktuálně dostupné cílové a zdrojové jazyky s ISO kódem a vlastním názvem. Používejte jej místo pevně zakódovaného seznamu – nové jazyky se zde objeví automaticky.

Spotřeba

GET/api/v1/usage

Koncový bod spotřeby zobrazuje pro každý klíč přeložená slova a vzniklé náklady aktuálního měsíce spolu s nastaveným měsíčním limitem. Stejná čísla vidíte graficky v zákaznické sekci pod „API a spotřeba“.

Chybové kódy

Chyby přicházejí jako JSON s poli error (strojově čitelný kód) a message (popis). Ošetřete alespoň tyto případy:

Limity & férovost

Standardně platí 60 požadavků za minutu na klíč a 30 000 znaků na požadavek; sandboxový klíč je navíc omezen na testovací kvótu. Vyšší limity uvolníme po krátké kontrole – kontaktujte nás s vaším případem užití.

Počítání slov: Počítají se slova zdrojového textu (hranice slov podle Unicode), jednou pro každý cílový jazyk. U formátů html a json se počítají pouze přeložitelné textové uzly nebo řetězcové hodnoty – značky, klíče a proměnné jsou zdarma.

Ochrana osobních údajů

Zpracování výhradně za účelem poskytování služeb na serverech v EU; obsah není používán k trénování modelů a je po 30 dnech vymazán z protokolů zpracování. Pro produkční využití uzavíráme smlouvu o zpracování osobních údajů podle čl. 28 GDPR – podrobnosti v Trust Center.

Prostřednictvím sandboxu neodesílejte žádné skutečné osobní údaje. Pseudonymizujte testovací obsah nebo používejte syntetické příklady.

Protokol změn

Červenec 2026

Spuštění veřejného sandboxu: koncové body překladů, dávek, glosářů, jazyků a spotřeby.

Plánováno

Samostatná správa produkčních klíčů, stylové profily podle značky, překladová paměť (Translation Memory) podle účtu.

API je verzována pod /v1; zpětně kompatibilní rozšíření (nová volitelná pole, nové jazyky) probíhají bez změny verze. Zlomové změny se objevují jako nová verze s minimálně dvanáctiměsíčním souběžným provozem.