API μετάφρασης κειμένου

Αυτό το API μεταφράζει κείμενο ως εργασίες σε ουρά, με μία γλώσσα προορισμού ανά εργασία. Υποβάλετε κείμενο, κρατήστε το αναγνωριστικό εργασίας που επιστρέφεται και ανακτάτε την εργασία μέχρι να ολοκληρωθεί η επεξεργασία. Στέλνετε κάθε αίτημα μέσω HTTPS με διαπιστευτήρια του λογαριασμού σας, είτε HTTP Basic όπως στα παραδείγματα είτε ένα διακριτικό API, όπως περιγράφεται στην ενότητα Έλεγχος ταυτότητας. Διατηρείτε τα διαπιστευτήρια στον διακομιστή σας.

Σημεία πρόσβασης

Οι δύο διακομιστές API, https://api.multi.tel και ο διακομιστής συμβατότητας https://api.multitel.net, μοιράζονται, στο πλαίσιο του λογαριασμού, τις εργασίες, τα κλειδιά ιδιοδυναμίας, τα όρια και τις χρεώσεις. Διαφέρουν στην εξωτερική δομή των απαντήσεων, οπότε χρησιμοποιείτε σταθερά τον ίδιο διακομιστή με κατάλληλο αναλυτή.

Στον api.multi.tel, κάθε διαδρομή είναι επίσης διαθέσιμη με το πρόθεμα /v1/translate αντί του /v3/translate. Στον api.multitel.net, χρησιμοποιήστε τις διαδρομές /v3/translate.

Η απάντηση πληροφοριών υπηρεσίας αναφέρει τα enabled, paidEnabled, mode (batch), realtime (false), maxSourceCharacters (20000), cpuLanguages και ratesNanosPerCharacter. Το cpuLanguages παραθέτει τους βασικούς κωδικούς γλώσσας που γίνονται δεκτοί για τυπική μετάφραση. Το ratesNanosPerCharacter δίνει τη διαμορφωμένη τιμή ανά σημείο κώδικα του αρχικού κειμένου για κάθε μηχανή, σε δισεκατομμυριοστά του δολαρίου ΗΠΑ: τιμή 5000 σημαίνει $5 ανά εκατομμύριο σημεία κώδικα. Η απάντηση δεν αναφέρει αν η βελτιωμένη μετάφραση είναι διαθέσιμη αυτή τη στιγμή· μια βελτιωμένη εκτίμηση επιστρέφει 503 όταν δεν είναι. Η ανάκτηση των πληροφοριών είναι δωρεάν.

Μετάφραση κειμένου

Στείλτε JSON με Content-Type: application/json στο POST https://api.multi.tel/v3/translate. Κάθε εργασία έχει μία γλώσσα προορισμού, οπότε υποβάλετε ξεχωριστή εργασία για κάθε προορισμό.

Οι κωδικοί τοπικών ρυθμίσεων είναι ετικέτες BCP 47 με 2 έως 63 γράμματα, ψηφία και παύλες. Μετατρέπονται σε κανονική μορφή, επομένως το en-us καταγράφεται ως en-US. Μη έγκυρες ετικέτες, καθώς και τα und, mul ή zxx, επιστρέφουν 400 invalid_translation_language. Η διαθεσιμότητα της τυπικής μετάφρασης ελέγχεται βάσει βασικής γλώσσας, και τα nb και nn υπολογίζονται ως no. Ένας περιφερειακός προορισμός όπως fr-CA γίνεται δεκτός και καταγράφεται, αλλά το τυπικό αποτέλεσμα ακολουθεί τη βασική γλώσσα και δεν είναι εγγυημένο ότι θα αποδίδει την περιφερειακή παραλλαγή.

Διατηρήστε το σώμα αιτήματος εντός 128 KiB σε αυτόν τον διακομιστή. Στείλτε το κείμενο ως UTF-8 αντί να χρησιμοποιείτε ακολουθία διαφυγής \u για κάθε χαρακτήρα εκτός ASCII, κάτι που μπορεί να κάνει ένα αίτημα 20,000 χαρακτήρων να υπερβεί το όριο.

Το σώμα δέχεται μόνο αυτά τα τέσσερα πεδία. Οποιαδήποτε άλλη ιδιότητα απορρίπτεται με 400 invalid_translation_request, συμπεριλαμβανομένων των idempotency_key, αναγνωριστικών κατόχου, ενδείξεων δωρεάν επεξεργασίας και πινάκων τμημάτων.

Ιδιοδυναμία και επαναχρησιμοποίηση

Κάθε υποβολή απαιτεί κεφαλίδα Idempotency-Key με 1 έως 190 χαρακτήρες. Χρησιμοποιήστε γράμματα ASCII, ψηφία, -, _, . και :, χωρίς αρχικά ή τελικά κενά· κλειδί που λείπει ή έχει τουλάχιστον 191 χαρακτήρες απορρίπτεται με 400. Τα κλειδιά περιορίζονται στον λογαριασμό σας και στη μετάφραση, και στους δύο διακομιστές και για όλα τα διαπιστευτήρια του λογαριασμού.

• Το ίδιο κλειδί με ίδιο κείμενο, ίδιες γλώσσες σε κανονική μορφή και ίδια μηχανή επιστρέφει την υπάρχουσα εργασία με HTTP 200 και duplicate: true, χωρίς νέα χρέωση.
• Το ίδιο κλειδί με διαφορετικό κείμενο, γλώσσες ή μηχανή επιστρέφει 409 idempotency_conflict. Το ίδιο κλειδί επιστρέφει επίσης 409 αν η έκδοση επεξεργασίας έχει αλλάξει από τη δημιουργία της εργασίας του. Σε αυτή την περίπτωση, ανακτήστε την αρχική εργασία με το αναγνωριστικό της αντί να την υποβάλετε ξανά.
• Νέο κλειδί με ίδιο κείμενο, ίδιες γλώσσες σε κανονική μορφή και ίδια μηχανή επιστρέφει την υπάρχουσα εργασία με HTTP 200 και duplicate: true, χωρίς νέα χρέωση επεξεργασίας, αν υπάρχει εργασία με αυτό το περιεχόμενο και την τρέχουσα έκδοση επεξεργασίας στην ουρά, σε εκτέλεση, ολοκληρωμένη ή σε αναμονή πληρωμής. Μια επαναχρησιμοποιημένη εργασία που περιμένει πληρωμή εξακολουθεί να χρειάζεται εξόφληση. Αποτυχημένες εργασίες δεν επαναχρησιμοποιούνται: δημιουργείται νέα εργασία και χρεώνεται όταν ολοκληρωθεί.

API_USER="your-api-username"
API_PASSWORD="your-api-password"

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: translation-example-001" \
  --data '{"text":"Please move my appointment to Tuesday at 3 PM, not 11 AM.","source_language":"en","target_language":"es","engine":"cpu"}' \
  -o translation-job.json \
  https://api.multi.tel/v3/translate

node -p 'JSON.parse(require("node:fs").readFileSync("translation-job.json","utf8")).data.id'

Μια νέα εργασία επιστρέφει HTTP 202. Το κείμενο του παραδείγματος έχει 57 σημεία κώδικα, επομένως με τιμή $5 ανά εκατομμύριο σημεία κώδικα κοστίζει $0.000285. Μια συντομευμένη απάντηση (το αναγνωριστικό είναι παράδειγμα):

{
  "status": "success",
  "data": {
    "id": "8b2e4c71-5d3a-4f09-a6e2-1c7f9d3b5a28",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "engine": "cpu",
    "sourceLocale": "en",
    "targetLocale": "es",
    "sourceCharacters": 57,
    "costUsd": "0.000285000",
    "costIsEstimate": true,
    "pricePerMillionCharactersUsd": "5.000000000",
    "progress": null
  }
}

Μια υποβολή μπορεί επίσης να επιστρέψει 402 insufficient_balance όταν το προπληρωμένο υπόλοιπο δεν καλύπτει την εργασία μαζί με τις άλλες εκκρεμείς εργασίες σας, και 429 translation_queue_full όταν ο λογαριασμός σας ή η υπηρεσία έχει υπερβολικά πολλές εκκρεμείς εργασίες. Επιστρέφει 503 στις εξής περιπτώσεις:

• paid_translation_not_enabled όσο η επί πληρωμή μετάφραση είναι απενεργοποιημένη.
• translation_unavailable για βελτιωμένο αίτημα όσο η βελτιωμένη μετάφραση δεν είναι διαθέσιμη.
• translation_pricing_unavailable όταν η επιλεγμένη μηχανή δεν έχει διαμορφωμένη τιμή.

Για απαντήσεις 429 και 503, δοκιμάστε αργότερα με το ίδιο κλειδί.

Επιλογή ποιότητας

Το μεγάλο κείμενο επεξεργάζεται σε μικρότερα μέρη και κατόπιν ενώνεται ξανά. Οι αλλαγές γραμμής και τα κενά μπορούν να αλλάξουν και μια πρόταση μπορεί να χάσει συμφραζόμενα στα όρια των μερών που επεξεργάζονται. Κρατήστε το αρχικό κείμενο και ελέγξτε το συναρμολογημένο αποτέλεσμα. Η τυπική μετάφραση χρησιμοποιεί τη βασική γλώσσα μιας περιφερειακής ετικέτας· η αποδοχή και καταγραφή της ετικέτας δεν εγγυάται περιφερειακή διατύπωση.

Η τυπική μετάφραση εκτελείται από διεργασίες επεξεργασίας σε CPU. Η βελτιωμένη μετάφραση στέλνει το κείμενο στη διαμορφωμένη εξωτερική υπηρεσία ΤΝ. Το αποτέλεσμά της εξακολουθεί να χρειάζεται έλεγχο· η υπηρεσία δεν εγγυάται ότι μια μηχανή είναι ακριβέστερη για κάθε ζεύγος γλωσσών ή είδος κειμένου.

Η τυπική μετάφραση είναι προσχέδιο, με ποιότητα και χρόνο επεξεργασίας που διαφέρουν ανά ζεύγος γλωσσών. Η βελτιωμένη μετάφραση προορίζεται για κείμενα όπου το πλαίσιο είναι σημαντικό, αλλά εξακολουθεί να απαιτεί έλεγχο σημαντικών ονομάτων, αριθμών, αρνήσεων και δεσμεύσεων. Καμία επιλογή δεν διορθώνει σφάλματα που ήδη υπάρχουν σε μια αρχική μεταγραφή, οπότε κρατήστε το πρωτότυπο για σύγκριση.

Χρησιμοποιήστε το GET /v3/translate στον ίδιο διακομιστή API για να ελέγξετε την τρέχουσα διαθεσιμότητα, τις υποστηριζόμενες τυπικές γλώσσες και τις διαμορφωμένες τιμές. Ένα τυπικό αίτημα του οποίου η βασική γλώσσα προέλευσης ή προορισμού δεν βρίσκεται στο cpuLanguages επιστρέφει 422 translation_language_pair_unavailable. Όταν παρέχεται source_language και έχει την ίδια βασική γλώσσα με τον προορισμό, το αίτημα επιστρέφει 409 translation_same_language αντί να δημιουργήσει εργασία. Η βελτιωμένη μετάφραση ενεργοποιείται χωριστά· όσο είναι μη διαθέσιμη, οι βελτιωμένες υποβολές και εκτιμήσεις επιστρέφουν 503.

Πρώτα ζητήστε εκτίμηση

Στον api.multi.tel, στείλτε το ίδιο σώμα JSON στο POST /v3/translate/estimate. Δεν απαιτείται κλειδί ιδιοδυναμίας. Η εκτίμηση εφαρμόζει την ίδια επικύρωση, συμπεριλαμβανομένων των ελέγχων 422 και 409, αλλά δεν δημιουργεί εργασία, δεν μεταφράζει κείμενο, δεν δεσμεύει χρήματα, δεν ελέγχει το υπόλοιπο και δεν χρεώνει τον λογαριασμό. Επιστρέφει HTTP 200 με estimate: true, charged: false, mode, realtime, engine, sourceCharacters, sourceLocale, targetLocale, pricePerMillionCharactersUsd και costUsd μέσα στο data. Για το παραπάνω παράδειγμα, το costUsd είναι 0.000285000 με την τυπική τιμή. Όσο η βελτιωμένη μετάφραση δεν είναι διαθέσιμη, μια βελτιωμένη εκτίμηση επιστρέφει 503 service_unavailable. Οι εκτιμήσεις χρησιμοποιούν την τρέχουσα διαμορφωμένη τιμή. Η τιμή μιας εργασίας ορίζεται κατά τη δημιουργία της και η χρέωση χρησιμοποιεί εκείνη την τιμή.

Ανάκτηση της μετάφρασης

Μια νέα υποβολή επιστρέφει HTTP 202, ενώ μια υπάρχουσα ή επαναχρησιμοποιημένη εργασία επιστρέφει HTTP 200. Κρατήστε το data.id και χρησιμοποιήστε την κοινή ροή εργασιών. Το αντικείμενο εργασίας περιέχει τα εξής πεδία:

• id, status, engine, sourceLocale και targetLocale.
• sourceCharacters, costUsd, costIsEstimate και pricePerMillionCharactersUsd.
• progress και createdAt.
• modelVersion, αδιαφανή συμβολοσειρά της έκδοσης επεξεργασίας.
• duplicate σε απαντήσεις που επαναχρησιμοποιούν εργασία.
• failureCode για αποτυχημένες εργασίες: translation_failed, translation_timeout, input_failed ή worker_lease_lost.

Μια αποτυχημένη εργασία εμφανίζει costUsd μηδέν.

Μια ολοκληρωμένη εργασία έχει data.result με sourceLocale (κενό αν δεν δόθηκε γλώσσα προέλευσης), targetLocale, το μεταφρασμένο κείμενο στο text (κείμενα τμημάτων ενωμένα με αλλαγές γραμμής) και segments. Για κείμενο που υποβάλλεται μέσω αυτού του API, το segments περιέχει μία εγγραφή με το μεταφρασμένο κείμενο στο text και τη γλώσσα προορισμού στο language. Τα αποτελέσματα εργασιών σε αναμονή πληρωμής παρακρατούνται μέχρι την εξόφληση.

Χρήση του api.multitel.net

Το σημείο πρόσβασης συμβατότητας POST https://api.multitel.net/v3/translate δέχεται τα ίδια πεδία JSON και την ίδια κεφαλίδα Idempotency-Key. Αν η κεφαλίδα λείπει, δέχεται επίσης συμβολοσειρά idempotency_key στο σώμα JSON. Κάθε άλλο επιπλέον πεδίο απορρίπτεται με 400 unsupported_translation_option. Σε αυτόν τον διακομιστή το ακατέργαστο σώμα μπορεί να φτάνει τα 256,000 bytes, και κείμενο πάνω από 20,000 σημεία κώδικα επιστρέφει 413 translation_too_large αντί για 400. Κενό source_language αντιμετωπίζεται ως παράλειψη. Μια απάντηση 429 περιλαμβάνει Retry-After: 15. Αυτός ο διακομιστής επιστρέφει επίσης τα εξής σφάλματα:

• 400 json_body_required όταν το σώμα λείπει, δεν είναι έγκυρο JSON ή είναι βαθμωτή τιμή JSON. Στείλτε αντικείμενο JSON.
• 400 invalid_translation_options όταν το text, το target_language ή το engine λείπει, είναι κενό ή δεν είναι συμβολοσειρά, ή το source_language δεν είναι συμβολοσειρά.
• 400 invalid_translation_text για κείμενο μόνο με λευκούς χαρακτήρες.
• 400 invalid_translation_engine για άγνωστη μηχανή.
• 400 idempotency_key_required για κλειδί που λείπει, είναι κενό ή υπερβολικά μεγάλο, ή για τιμή idempotency_key που δεν είναι συμβολοσειρά.
• 400 invalid_job για αναγνωριστικό εργασίας με λανθασμένη μορφή.

Οι απαντήσεις της υπηρεσίας μετάφρασης αυτού του διακομιστή χρησιμοποιούν την εξωτερική δομή {"status":{"code":HTTP_STATUS},"response":{...}}, όπου το status είναι αντικείμενο. Διαβάστε το αναγνωριστικό εργασίας από το response.id και το ολοκληρωμένο αποτέλεσμα από το response.result. Στα σφάλματα ο κωδικός βρίσκεται στο response.code, χωρίς μήνυμα ή αναγνωριστικό αιτήματος. Οι αποτυχίες ελέγχου ταυτότητας (401) επιστρέφονται από τον γενικό έλεγχο σύνδεσης του διακομιστή και μπορεί να έχουν διαφορετικό σώμα, γι’ αυτό ελέγξτε την κατάσταση HTTP πριν από την ανάλυση. Οι εργασίες είναι κοινές με τον κύριο διακομιστή, αλλά χρησιμοποιήστε τον ίδιο διακομιστή για περιοδικό έλεγχο, εξόφληση και χρήση, ώστε ο αναλυτής σας να αντιστοιχεί στην εξωτερική δομή. Ο διακομιστής δέχεται επίσης τα ίδια πεδία JSON στο /v3/translate/estimate χωρίς κλειδί ιδιοδυναμίας, και η εκτίμησή του βρίσκεται μέσα στο response.