Kehittäjät

API-dokumentaatio

Kaikki mitä tarvitset Baduno Translation API:n integrointiin: todennus, päätepisteet, esimerkit, virhekoodit ja rajoitukset. Perus-URL kaikille kutsuille on https://www.baduno.com/api/v1 – vain HTTPS:n kautta.

Perus-URLhttps://www.baduno.com/api/v1

Johdanto

Käännös-API kääntää tekstiä, HTML:ää ja rakenteellista JSON:ia jopa 24 EU-virkakielelle. Pyynnöt ja vastaukset ovat JSON-muodossa (UTF-8). Jokainen pyyntö valitsee laatutason: basic (AI), pro (AI terminologian varmistuksella) tai review (lisäksi äidinkielinen pistokokein tarkistus, asynkroninen).

Kokeilua varten käytä asiakasalueen julkista hiekkalaatikkoavainta – se toimii kuten tuotanto, mutta on rajoitettu testauskiintiöön. Tuotantoavaimen saat lyhyen aktivoinnin jälkeen asiakastilisi kautta.

Julkinen hiekkalaatikkoavainbd_test_sandbox_2026

Todennus

Jokainen pyyntö sisältää API-avaimesi Authorization-otsakkeessa Bearer-tokenina. Avaimet alkavat bd_test_ (hiekkalaatikko) tai bd_live_ (tuotanto). Käsittele avaimia kuten salasanoja: älä koskaan etupään koodissa, älä koskaan repossa – jos epäilet tietovuotoa, peruuta ja luo uusi asiakasalueella.

Pyynnöt ilman kelvollista avainta palauttavat API:lta tilan 401. Avaimelle voidaan milloin tahansa asettaa kuukausittainen sanarajoitus; sen saavuttaessa API palauttaa tilan 402, kunnes nostat rajaa.

Header

Authorization: Bearer bd_live_ihr_schluessel

Tekstin kääntäminen

POST/api/v1/translate

Keskeinen päätepiste kääntää yhden tai useamman tekstin kohdekielelle. Kenttä format ohjaa käsittelyä: text (oletus), html (merkintä säilyy) tai json (vain merkkijonoarvot käännetään, avaimet ja rakenne säilyvät muuttumattomina).

Vastaus sisältää käännökset syöttöjärjestyksessä, lasketut lähdesanat ja lasketut kustannukset sentteinä. Valinnaisella Idempotency-Key-otsakkeella estät kaksoiskäsittelyn verkko- uusinnoissa: identtiset avaimet palauttavat tallennetun ensimmäisen vastauksen.

Pyyntö · curl

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

Vastaus

{
  "ok": true,
  "target": "fr",
  "tier": "basic",
  "translations": ["Livraison gratuite à partir de 50 euros."],
  "words": 6,
  "cost_cents": 12,
  "detected_source": "de"
}

Parametri

`target`	Kohdekieli (ISO 639-1), esim. fr, it, pl. Pakollinen kenttä.
`texts[]`	Luettelo käännettävistä teksteistä (1–50 per pyyntö, yhteensä enintään 30 000 merkkiä).
`source`	Lähdekieli (ISO 639-1). Valinnainen – jos ei määritetä, se tunnistetaan automaattisesti.
`format`	text, html tai json. Oletus: text.
`tier`	Laatutaso basic, pro tai review. Oletus: basic.
`glossary`	Tallennetun sanaston tunnus, jonka terminologiaa sovelletaan (tasot pro ja review).

JavaScript

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

Python

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

PHP

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

Erä ja Webhooks

POST/api/v1/batches

Suurille määrille tai tarkistusvaiheelle työskentelet asynkronisesti: Eräpäätepiste ottaa vastaan enintään 1 000 tekstiä ja vastaa heti työn tunnuksella. Kun työ on valmis – tarkistusvaiheessa äidinkielisen otoksen jälkeen – API kutsuu tallennettua webhook-osoitettasi tuloksella.

Webhook-kutsut on allekirjoitettu HMAC-SHA-256-otsakkeella, jonka voit tarkistaa webhook-salaisuudellasi. Jos palvelimesi ei vastaa tilakoodilla 2xx, toimitus toistetaan enintään viisi kertaa kasvavin välein; työt ovat lisäksi haettavissa GET-pyynnöllä 30 päivän ajan.

Batch-Ablauf

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

Sanastot

POST/api/v1/glossaries

Sanastot turvaavat terminologian: jokainen merkintä sisältää lähdetermin ja sen sitovan käännöksen kohdekielelle. Lataus tehdään CSV-muodossa asiakasalueella tai API:n kautta; pro- ja review-tasot käyttävät osumia sitovina, basic käyttää niitä suosituksena.

Jokaisella tilillä voi olla enintään 20 sanastoa, kussakin 5 000 merkintää. Muutokset vaikuttavat välittömästi kaikkiin seuraaviin pyyntöihin – versioikaa siis sanastoja kuten koodia ja testatkaa muutokset ensin sandbox-avaimella.

Kielet

GET/api/v1/languages

Kielten päätepiste tarjoaa käytettävissä olevat kohde- ja lähdekielet ISO-koodeineen ja omakielisine nimineen. Käytä sitä kiinteän listan sijaan – uudet kielet ilmestyvät sinne automaattisesti.

Kulutus

GET/api/v1/usage

Kulutuksen päätepiste näyttää avaimittain kuluvan kuukauden käännetyt sanat ja syntyneet kustannukset sekä asetetun kuukausittaisen rajan. Samat luvut näet graafisesti asiakasalueella kohdassa "API & Kulutus".

Virhekoodit

Virheet tulevat JSON-muodossa kenttien error (koneellisesti luettava koodi) ja message (kuvaus) kanssa. Käsittele vähintään nämä tapaukset:

401	`invalid_key`	Puuttuva tai virheellinen API-avain.
402	`quota_exceeded`	Kuukausiraja tai saldo loppu – nosta rajaa asiakasalueella.
413	`payload_too_large`	Pyyntö liian suuri – jaa tekstit (max. 30 000 merkkiä per pyyntö).
422	`unsupported_language`	Kohdekieli ei saatavilla tai parametri virheellinen – tiedot message-kentässä.
429	`rate_limited`	Nopeusrajoitus saavutettu – toista eksponentiaalisella viiveellä; Retry-After-otsikko kertoo odotusajan.
500	`internal`	Odottamaton virhe palvelimellamme – odota hetki ja yritä uudelleen; toistuessa ota yhteyttä tukeen.

Rajoitukset ja oikeudenmukaisuus

Oletuksena on 60 pyyntöä minuutissa avainta kohden sekä 30 000 merkkiä pyyntöä kohden; hiekkalaatikkoavaimen testikiintiö on lisäksi rajoitettu. Korkeammat rajat vapautamme lyhyen tarkastuksen jälkeen – ilmoita käyttötapauksesi.

Sanalaskenta: Lasketaan lähdetekstin sanat (Unicode-sananrajat), kerran kohdekieltä kohden. HTML- ja JSON-muodoissa lasketaan vain käännettävät tekstisolmut ja merkkijonoarvot – markup, avaimet ja muuttujat eivät maksa mitään.

Tietosuoja

Käsittely yksinomaan palvelun tuottamiseen EU-palvelimilla; sisältöä ei käytetä mallien kouluttamiseen ja se poistetaan käsittelylokeista 30 päivän jälkeen. Tuotantokäyttöä varten teemme tietojenkäsittelysopimuksen GDPR:n 28 artiklan mukaisesti – tiedot Trust Centeristä.

Älä lähetä henkilötietoja hiekkalaatikon kautta. Pseudonymisoi testisisällöt tai käytä synteettisiä esimerkkejä.

Muutosloki

heinäkuu 2026: Julkisen sandboxin käynnistys: käännös-, erä-, sanasto-, kieli- ja kulutuspäätepisteet.
Suunniteltu: Tuotantoavainten itsehallinta, tyyliprofiilit tuotemerkille, käännösmuisti (Translation Memory) tiliä kohti.

API on versioitu polulla /v1; taaksepäin yhteensopivat laajennukset (uudet valinnaiset kentät, uudet kielet) toteutetaan ilman versionvaihtoa. Rikkovat muutokset esitellään uutena versiona, jota ajetaan rinnakkain vähintään kaksitoista kuukautta.

Pyydä sitoumukseton tarjous

Vastaus 24 tunnin sisällä arkipäivisin.