API документация

Въведение

Translation API превежда текст, HTML и структуриран JSON на до 24 официални езика на ЕС. Заявките и отговорите са в JSON (UTF-8). Всяка заявка избира ниво на качество: basic (AI), pro (AI с прилагане на терминология) или review (допълнителна проверка на извадка от носители на езика, асинхронна).

За изпробване използвайте публичния sandbox ключ от клиентската зона – той работи като продукционния, но е ограничен до тестов квот. Продукционният ключ получавате след кратко активиране чрез вашия клиентски акаунт.

Публичен sandbox ключbd_test_sandbox_2026

Удостоверяване

Всяка заявка носи вашия API ключ в заглавката Authorization като Bearer токен. Ключовете започват с bd_test_ (sandbox) или bd_live_ (продукция). Отнасяйте се с ключовете като с пароли: никога в предния код (frontend) или хранилището – при съмнение за компрометиране анулирайте и генерирайте нови в клиентската зона.

Заявките без валиден ключ получават отговор с код 401. Ключът може по всяко време да бъде ограничен с месечен лимит в думи; при достигане API отговаря с код 402, докато не увеличите лимита.

Authorization: Bearer bd_live_ihr_schluessel

Превод на текст

POST/api/v1/translate

Централната крайна точка превежда един или няколко текста на целеви език. Полето format управлява обработката: text (по подразбиране), html (маркирането се запазва) или json (само низовите стойности се превеждат, ключовете и структурата остават непроменени).

Отговорът съдържа преводите в реда на въвеждане, преброените изходни думи и изчислените разходи в центове. С опционалния заглавен параметър Idempotency-Key предотвратявате дублираща обработка при повторение на мрежови заявки: идентични ключове връщат запазения първоначален отговор.

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

Параметър

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

Пакетни заявки и уебкукове

POST/api/v1/batches

За големи обеми или за етапа на преглед работете асинхронно: Крайната точка за пакетни заявки приема до 1 000 текста и отговаря незабавно с идентификатор на задача. След като задачата приключи – при преглед след проверка на извадка от носители на езика – API извиква предоставения от вас URL на уебкук с резултата.

Извикванията на уебкукове са подписани с HMAC-SHA-256 заглавка, която проверявате с вашата тайна за уебкук. Ако вашият сървър не отговори със статус 2xx, доставката се повтаря до пет пъти с нарастващ интервал; задачите остават достъпни за GET заявки допълнителни 30 дни.

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

Глосари

POST/api/v1/glossaries

Глосарите осигуряват вашата терминология: всеки запис съдържа изходен термин и неговия задължителен превод за всеки целеви език. Качват се като CSV в клиентската зона или чрез API; нивото pro и review прилагат задължително съвпаденията, а basic ги използва като препоръка.

На сметка са възможни до 20 глосара с по 5 000 записа. Промените влизат в сила незабавно за всички последващи заявки – затова версионирайте глосарите като код и тествайте промените първо със sandbox ключа.

Езици

GET/api/v1/languages

Крайната точка за езици предоставя актуално наличните целеви и изходни езици с ISO код и собствено наименование. Използвайте я вместо твърдо зададен списък – новите езици се появяват там автоматично.

Консумация

GET/api/v1/usage

Крайната точка за консумация показва за всеки ключ преведените думи и направените разходи за текущия месец, както и зададения месечен лимит. Същите числа виждате графично в клиентската зона под „API & Консумация“.

Кодове за грешки

Грешките идват като JSON с полетата error (машинночетим код) и message (описание). Обработвайте поне тези случаи:

Лимити и справедливост

По подразбиране се прилагат 60 заявки на минута на ключ и 30 000 знака на заявка; sandbox ключът е допълнително ограничен до тестовото квота. По-високи лимити се активират след кратък преглед – свържете се с нас с вашия случай на употреба.

Броене на думи: Преброяват се думите в изходния текст (граници на думите по Unicode), по веднъж за всеки целеви език. При формат html и json се броят само превеждаеми текстови възли или низови стойности – маркировката, ключовете и променливите не се таксуват.

Защита на данните

Обработка единствено за предоставяне на услуги на сървъри в ЕС; съдържанието не се използва за обучение на модели и се изтрива от регистрите за обработка след 30 дни. За производствена употреба сключваме договор за обработка на данни съгласно чл. 28 от ОРЗД – подробности в Trust Center.

Не изпращайте реални лични данни чрез Sandbox. Псевдонимизирайте тестовото съдържание или използвайте синтетични примери.

Протокол за промени

Юли 2026

Старт на публичната пясъчна среда: крайна точка за преводи, пакети, речници, езици и потребление.

Планирано

Самоуправление на продуктивни ключове, стилови профили за марка, памет за преводи (Translation Memory) за акаунт.

API е версионирана под /v1; обратно съвместими разширения (нови незадължителни полета, нови езици) се извършват без смяна на версията. Промени, нарушаващи съвместимостта, се появяват като нова версия с поне дванадесет месеца паралелна работа.