API dokumentacija

Įvadas

Vertimo API verčia tekstą, HTML ir struktūrizuotą JSON į iki 24 Europos Sąjungos oficialių kalbų. Užklausos ir atsakymai yra JSON (UTF-8). Kiekvienoje užklausoje pasirenkamas kokybės lygis: basic (AI), pro (AI su terminologijos užtikrinimu) arba review (papildomai atliekama gimtosios kalbos patikra, asinchroniškai).

Norėdami išbandyti, naudokite viešąjį smėlio dėžės raktą iš klientų srities – jis elgiasi kaip gamybinis, tačiau ribotas testavimo kvota. Gamybinius raktus gausite po trumpo aktyvavimo per savo kliento paskyrą.

Viešasis bandomosios aplinkos raktasbd_test_sandbox_2026

Autentifikacija

Kiekviena užklausa turi jūsų API raktą Authorization antraštėje kaip Bearer tokeną. Raktai prasideda bd_test_ (smėlio dėžė) arba bd_live_ (gamybinė). Raktus saugokite kaip slaptažodžius: niekada priekinės dalies kode, niekada saugykloje – įtarus kompromitaciją, panaikinkite ir sukurkite naują klientų srityje.

Užklausas be galiojančio rakto API atsako su 401 būsena. Raktą galima bet kada apriboti mėnesio žodžių limitu; jį pasiekus API atsako su 402 būsena, kol padidinsite limitą.

Authorization: Bearer bd_live_ihr_schluessel

Teksto vertimas

POST/api/v1/translate

Centrinis galinis taškas verčia vieną ar daugiau tekstų į tikslinę kalbą. Laukas format valdo apdorojimą: text (numatytasis), html (žymėjimas išsaugomas) arba json (verčiamos tik eilutės reikšmės, raktai ir struktūra lieka nepakeisti).

Atsakyme pateikiami vertimai įvesties tvarka, suskaičiuoti šaltinio žodžiai ir apskaičiuotos sąnaudos centais. Naudodami pasirinktinę antraštę Idempotency-Key išvengsite dvigubo apdorojimo tinklo pakartojimų atveju: identiški raktai grąžina išsaugotą pirmąjį atsakymą.

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

Parametras

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

Paketinis apdorojimas ir Webhook'ai

POST/api/v1/batches

Dideliems kiekiams arba peržiūros etapui dirbkite asinchroniškai: Paketinio apdorojimo galinė priima iki 1 000 tekstų ir nedelsiant atsako darbo ID. Kai darbas baigtas – peržiūros atveju po gimtosios kalbos atsitiktinių patikrinimų – API iškviečia jūsų pateiktą žiniatinklio iškviečiamojo URL su rezultatu.

Žiniatinklio iškviečiamieji yra pasirašyti HMAC-SHA-256 antrašte, kurią jūs tikrinate naudodami savo žiniatinklio iškviečiamojo slaptą raktą. Jei jūsų serveris neatsako būsenos kodu 2xx, pristatymas kartojamas iki penkių kartų didėjančiais intervalais; darbai lieka pasiekiami per GET dar 30 dienų.

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

Glosarijai

POST/api/v1/glossaries

Glosarijai užtikrina jūsų terminologiją: kiekvienas įrašas turi šaltinio terminą ir privalomą jo vertimą kiekviena tiksline kalba. Įkeliama kaip CSV failas kliento zonoje arba per API; lygiai 'pro' ir 'review' įtvirtina atitikmenis kaip privalomus, 'basic' naudoja juos kaip rekomendaciją.

Kiekvienoje paskyroje galima sukurti iki 20 glosarijų, kiekviename iki 5.000 įrašų. Pakeitimai įsigalioja visoms vėlesnėms užklausoms – todėl versijuokite glosarijus kaip kodą ir pirmiausia išbandykite pakeitimus naudodami 'sandbox' raktą.

Kalbos

GET/api/v1/languages

Kalbų galutinis taškas pateikia šiuo metu pasiekiamas tikslo ir šaltinio kalbas su ISO kodu ir savu pavadinimu. Naudokite jį vietoj fiksuoto sąrašo – naujos kalbos ten atsiranda automatiškai.

Sąnaudos

GET/api/v1/usage

Sąnaudų pabaigos taškas pagal kiekvieną raktą rodo išverstus žodžius, patirtas einamojo mėnesio išlaidas ir nustatytą mėnesio limitą. Tuos pačius skaičius matote grafiškai kliento srityje skiltyje „API ir sąnaudos“.

Klaidų kodai

Klaidos pateikiamos JSON formatu su laukais error (mašininio skaitymo kodas) ir message (aprašymas). Apdorokite bent šiuos atvejus:

Ribos ir sąžiningumas

Pagal nutylėjimą galioja 60 užklausų per minutę vienam raktui ir 30 000 simbolių vienai užklausai; smėlio dėžės raktas papildomai ribojamas bandomuoju kontingentu. Didesnius limitus atlaisviname po trumpo patikrinimo – praneškite apie savo naudojimo atvejį.

Žodžių skaičiavimas: Skaičiuojami šaltinio teksto žodžiai (Unikodo žodžių ribos), kiekvienai tikslinei kalbai atskirai. Esant html ir json formatams, skaičiuojami tik verčiami teksto mazgai arba eilutės reikšmės – žymėjimas, raktai ir kintamieji nieko nekainuoja.

Duomenų apsauga

Apdorojimas tik paslaugų teikimui ES serveriuose; turinys nenaudojamas modelių mokymui ir po 30 dienų ištrinamas iš apdorojimo žurnalų. Gamybiniam naudojimui sudarome duomenų tvarkymo sutartį pagal BDAR 28 str. – išsami informacija Trust Centre.

Nesiųskite per smėlio dėžę tikrų asmens duomenų. Pseudonimizuokite testinį turinį arba naudokite sintetinius pavyzdžius.

Pakeitimų protokolas

2026 m. liepa

Viešosios smėlio dėžės paleidimas: vertimo, paketinio, glosarijaus, kalbų ir vartojimo galiniai taškai.

Planuojama

Produktyvaus rakto savitvarka, stiliaus profiliai pagal prekės ženklą, vertimo atmintis (Translation Memory) pagal paskyrą.

API versijuojama per /v1; atgal suderinami išplėtimai (nauji pasirinktiniai laukai, naujos kalbos) atliekami nekeičiant versijos. Pertraukiantys pakeitimai pateikiami kaip nauja versija, veikianti lygiagrečiai mažiausiai dvylika mėnesių.