API-dokumentáció

Bevezetés

A Fordítási API szöveget, HTML-t és strukturált JSON-t fordít akár 24 EU-hivatalos nyelvre. A kérések és válaszok JSON formátumúak (UTF-8). Minden kérés kiválaszt egy minőségi szintet: basic (AI), pro (AI terminológia-érvényesítéssel) vagy review (további anyanyelvi mintavételes ellenőrzés, aszinkron).

A kipróbáláshoz használja az ügyfélportálon elérhető nyilvános sandbox-kulcsot – ugyanúgy működik, mint az éles, de tesztkvótára korlátozódik. Az élesítési kulcsot rövid aktiválás után kapja meg az ügyfélfiókján keresztül.

Nyilvános sandbox-kulcsbd_test_sandbox_2026

Hitelesítés

Minden kérés tartalmazza az API-kulcsot az Authorization fejlécben Bearer tokenként. A kulcsok bd_test_ (sandbox) vagy bd_live_ (éles) előtaggal kezdődnek. Kezelje a kulcsokat jelszavakként: soha ne a frontend kódban, soha ne a repository-ban – kompromittálódás gyanúja esetén vonja vissza és hozzon létre újat az ügyfélportálon.

Az érvénytelen kulcsú kérésekre az API 401-es állapotkóddal válaszol. A kulcs bármikor ellátható havi szókorláttal; a korlát elérésekor az API 402-es állapotkóddal válaszol, amíg Ön meg nem emeli a korlátot.

Authorization: Bearer bd_live_ihr_schluessel

Szöveg fordítása

POST/api/v1/translate

A központi végpont egy vagy több szöveget fordít le egy célnyelvre. A format mező szabályozza a kezelést: text (alapértelmezett), html (a jelölés megmarad) vagy json (csak a string típusú értékek kerülnek fordításra, a kulcsok és a struktúra változatlanok maradnak).

A válasz tartalmazza a fordításokat a bemeneti sorrendben, a megszámolt forrásszavakat és a számított költségeket centben. Az opcionális Idempotency-Key fejléc segítségével elkerülheti a dupla feldolgozást hálózati újraküldések esetén: azonos kulcsok esetén a tárolt első válasz kerül visszaadásra.

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

Paraméter

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 & Webhookok

POST/api/v1/batches

Nagy mennyiségek vagy a felülvizsgálati szint esetén aszinkron módon dolgozzon: A Batch-végpont legfeljebb 1.000 szöveget fogad el, és azonnal egy feladat-azonosítóval válaszol. Amint a feladat befejeződött – felülvizsgálat esetén az anyanyelvi mintavétel után – az API meghívja az Ön által megadott webhook URL-t az eredménnyel.

A webhook-hívások egy HMAC-SHA-256 fejléccel vannak aláírva, amelyet az Ön webhook-titkával ellenőrizhet. Ha a kiszolgáló nem 2xx állapotkóddal válaszol, a kézbesítés legfeljebb ötször, növekvő időközönként megismétlődik; a feladatok további 30 napig GET segítségével lekérhetők.

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

Glosszáriumok

POST/api/v1/glossaries

A glosszáriumok biztosítják a terminológiát: minden bejegyzés egy forráskifejezésből és annak kötelező fordításából áll célnyelvenként. Feltöltés CSV formátumban az ügyfélfelületen vagy API-n keresztül; a pro és review szint kötelezővé teszi a találatokat, a basic ajánlásként használja.

Fiókonként legfeljebb 20 glosszárium lehetséges, egyenként 5 000 bejegyzéssel. A módosítások azonnal hatnak az összes későbbi kérésre – ezért verziózza a glosszáriumokat kódként, és először a sandbox-kulccsal tesztelje a változtatásokat.

Nyelvek

GET/api/v1/languages

A nyelvek végpont a jelenleg elérhető cél- és forrásnyelveket adja meg ISO-kóddal és saját elnevezéssel. Használja ezt egy mereven bekódolt lista helyett – az új nyelvek automatikusan megjelennek ott.

Fogyasztás

GET/api/v1/usage

A fogyasztási végpont kulcsonként mutatja az aktuális hónap lefordított szavait és felmerült költségeit, valamint a beállított havi limitet. Ugyanezeket a számokat grafikusan is láthatja az ügyfélportál „API és fogyasztás” alatt.

Hibakódok

A hibák JSON formátumban érkeznek, az error (géppel olvasható kód) és message (leírás) mezőkkel. Legalább az alábbi eseteket kezelje:

Korlátok és méltányosság

Alapértelmezés szerint percenként 60 kérés és kulcsonként 30 000 karakter érvényes kérésenként; a homokozó kulcs emellett a tesztkvótára korlátozódik. Magasabb korlátokat rövid ellenőrzés után feloldunk – jelentkezzen a használati esetével.

Szószámlálás: A forrásszöveg szavai számítanak (Unicode szóhatárok), célnyelvenként egyszer. HTML és JSON formátum esetén csak a lefordítható szöveges csomópontok, illetve karakterlánc-értékek számítanak – a jelölőnyelvi elemek, kulcsok és változók nem kerülnek beleszámításra.

Adatvédelem

Feldolgozás kizárólag a szolgáltatásnyújtás céljából, EU-szervereken; a tartalmakat nem használjuk modellek betanítására, és 30 nap elteltével töröljük a feldolgozási naplókból. Éles üzemi használat esetén a GDPR 28. cikke szerinti adatfeldolgozási szerződést kötünk – részletek a Trust Centerben.

Ne küldjön személyes valós adatokat a sandboxon keresztül. A teszt tartalmakat álnevesítse, vagy használjon szintetikus példákat.

Változási napló

2026. július

Nyilvános sandbox indítása: fordítási, batch, glosszárium, nyelvek és fogyasztás végpontok.

Tervezett

Termelési kulcsok önkezelése, stílusprofilok márkánként, fordítási memória fiókonként.

Az API a /v1 alatt van verziózva; a visszafelé kompatibilis bővítések (új opcionális mezők, új nyelvek) verzióváltás nélkül történnek. A megszakító változtatások új verzióként jelennek meg, legalább tizenkét hónapos párhuzamos üzemeltetéssel.