Τεκμηρίωση API

Εισαγωγή

Το Translation API μεταφράζει κείμενο, HTML και δομημένο JSON σε έως 24 επίσημες γλώσσες της ΕΕ. Τα αιτήματα και οι απαντήσεις είναι σε JSON (UTF-8). Κάθε αίτημα επιλέγει ένα επίπεδο ποιότητας: basic (AI), pro (AI με επιβολή ορολογίας) ή review (επιπλέον δειγματοληπτικός έλεγχος από φυσικούς ομιλητές, ασύγχρονα).

Για δοκιμή, χρησιμοποιήστε το δημόσιο κλειδί sandbox από τον πελατοκεντρικό τομέα – συμπεριφέρεται όπως η παραγωγή, αλλά περιορίζεται σε ένα δοκιμαστικό όριο. Τα κλειδιά παραγωγής λαμβάνετε μετά από σύντομη ενεργοποίηση μέσω του λογαριασμού πελάτη σας.

Δημόσιο κλειδί sandboxbd_test_sandbox_2026

Αυθεντικοποίηση

Κάθε αίτημα φέρει το κλειδί API σας στην κεφαλίδα Authorization ως Bearer token. Τα κλειδιά ξεκινούν με bd_test_ (sandbox) ή bd_live_ (παραγωγή). Αντιμετωπίστε τα κλειδιά όπως τους κωδικούς πρόσβασης: ποτέ σε κώδικα frontend, ποτέ στο αποθετήριο – σε περίπτωση υποψίας παραβίασης, ανακαλέστε τα στον πελατοκεντρικό τομέα και δημιουργήστε νέα.

Τα αιτήματα χωρίς έγκυρο κλειδί λαμβάνουν από το API κατάσταση 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);

Batch & Webhooks

POST/api/v1/batches

Για μεγάλες ποσότητες ή το στάδιο ελέγχου, εργαστείτε ασύγχρονα: Το batch endpoint δέχεται έως 1.000 κείμενα και απαντά άμεσα με ένα job ID. Μόλις ολοκληρωθεί η εργασία – για έλεγχο μετά από το δείγμα μητρικής γλώσσας – το API καλεί την καταχωρημένη webhook URL σας με το αποτέλεσμα.

Οι κλήσεις webhook υπογράφονται με μια κεφαλίδα HMAC-SHA-256, την οποία επαληθεύετε με το μυστικό webhook σας. Εάν ο διακομιστής σας δεν απαντήσει με κατάσταση 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

Έναρξη του δημόσιου sandbox: τελικά σημεία μετάφρασης, μαζικής επεξεργασίας, γλωσσαρίου, γλωσσών και κατανάλωσης.

Προγραμματισμένο

Αυτοδιαχείριση παραγωγικών κλειδιών, Στυλ προφίλ ανά μάρκα, Μνήμη μετάφρασης (Translation Memory) ανά λογαριασμό.

Η API έχει έκδοση στο /v1· οι συμβατές προς τα πίσω επεκτάσεις (νέα προαιρετικά πεδία, νέες γλώσσες) γίνονται χωρίς αλλαγή έκδοσης. Οι ασύμβατες αλλαγές εμφανίζονται ως νέα έκδοση με τουλάχιστον δώδεκα μήνες παράλληλης λειτουργίας.