Αντικαταστήστε το παρακάτω SERVICE με speech_to_text ή translate και το JOB_ID με το UUID που επιστρέφεται. Όλες οι ενέργειες απαιτούν διαπιστευτήρια του λογαριασμού σας, όπως περιγράφεται στην ενότητα Έλεγχος ταυτότητας, και περιορίζονται στον λογαριασμό στον οποίο ανήκει η εργασία. Μπορείτε να ανακτήσετε μια εργασία από οποιονδήποτε από τους δύο διακομιστές API, αλλά κάθε διακομιστής χρησιμοποιεί τη δική του εξωτερική δομή απάντησης, επομένως χρησιμοποιείτε σταθερά τον ίδιο διακομιστή.
| Διακομιστής | Επιτυχία | Σφάλμα |
|---|---|---|
api.multi.tel | {"status":"success","data":{...}} | {"status":"error","code":"...","message":"...","requestId":"..."} |
api.multitel.net | {"status":{"code":200},"response":{...}} | {"status":{"code":409},"response":{"code":"idempotency_conflict"}} |
Στον api.multitel.net, οι αποτυχίες ελέγχου ταυτότητας (401) επιστρέφονται πριν εφαρμοστεί αυτή η εξωτερική δομή και μπορεί να έχουν διαφορετικό σώμα απάντησης. Ελέγχετε επομένως τον κωδικό κατάστασης HTTP πριν από την ανάλυση της απάντησης.
Έλεγχος ταυτότητας
Κάθε αίτημα πρέπει να περιλαμβάνει διαπιστευτήρια του λογαριασμού σας. Οι εργασίες, τα κλειδιά ιδιοδυναμίας, τα όρια, η χρήση και οι χρεώσεις ανήκουν στον λογαριασμό στον οποίο ανήκουν τα διαπιστευτήρια. Είναι κοινά για όλα τα διαπιστευτήρια αυτού του λογαριασμού και στους δύο διακομιστές, ανεξάρτητα από το ποια διαπιστευτήρια χρησιμοποιούνται για την αποστολή του αιτήματος.
- HTTP Basic (
Authorization: Basicήcurl --user). Γίνονται δεκτά τα διαπιστευτήρια λογαριασμού API τύπου κωδικού πρόσβασης, υπολογαριασμού ή του λογαριασμού σύνδεσής σας. Συνιστούμε έναν αποκλειστικό λογαριασμό API. Το όνομα χρήστη δεν μπορεί να περιέχει άνω και κάτω τελεία και ούτε το όνομα χρήστη ούτε ο κωδικός πρόσβασης μπορούν να είναι κενά. - Διακριτικό Bearer (
Authorization: Bearer YOUR_TOKEN). Γίνεται δεκτό για λογαριασμό API τύπου διακριτικού. Οι λογαριασμοί API τύπου διακριτικού πρέπει να έχουν περιορισμό IP και τα αιτήματα πρέπει να προέρχονται από επιτρεπόμενη διεύθυνση. Και οι δύο διακομιστές API δέχονται τις διευθύνσεις IPv4 και τις περιοχές CIDR που έχουν οριστεί για τον λογαριασμό. Δεν μπορείτε να στείλετε ένα διακριτικό ως κωδικό πρόσβασης Basic. Επιβεβαιώστε ότι το διακριτικό σας λειτουργεί στον διακομιστή που χρησιμοποιείτε.
API_TOKEN="your-api-token"
curl --fail-with-body --silent --show-error \
-H "Authorization: Bearer $API_TOKEN" \
https://api.multi.tel/v3/speech_to_textΑν ένας λογαριασμός API έχει περιορισμό διεύθυνσης IP, στέλνετε τα αιτήματα από επιτρεπόμενη διεύθυνση. Τα ελλιπή ή μη έγκυρα διαπιστευτήρια επιστρέφουν 401. Στον api.multitel.net, τα έγκυρα διαπιστευτήρια που δεν μπορούν να χρησιμοποιήσουν αυτές τις υπηρεσίες, όπως διαπιστευτήρια λογαριασμού διακριτικού που αποστέλλονται ως Basic, επιστρέφουν 403 unsupported_transcription_principal ή unsupported_translation_principal. Οι επανειλημμένες αποτυχημένες απόπειρες ελέγχου ταυτότητας από μία διεύθυνση στον api.multitel.net μπορεί να οδηγήσουν σε αποκλεισμό της διεύθυνσης. Διορθώστε λοιπόν τα διαπιστευτήρια πριν δοκιμάσετε ξανά.
Ελέγχετε περιοδικά την ολοκλήρωση
Στείλτε αίτημα GET /v3/SERVICE/JOB_ID. Συνιστούμε να ελέγχετε την κατάσταση το πολύ μία φορά κάθε 3 δευτερόλεπτα. Η εξωτερική δομή της απάντησης περιγράφει το αίτημα. Εξετάστε το πεδίο status της εργασίας στο εσωτερικό της για να διαπιστώσετε αν η επεξεργασία έχει ολοκληρωθεί.
| Κατάσταση | Σημασία |
|---|---|
queued | Έγινε αποδεκτή και βρίσκεται σε αναμονή. Οι εργασίες ενός λογαριασμού εκτελούνται μία κάθε φορά, εναλλάξ με εκείνες των άλλων λογαριασμών. |
running | Εκτελείται επεξεργασία. Το progress μπορεί να είναι null. Μια τιμή null από μόνη της δεν σημαίνει ότι η εργασία έχει κολλήσει. |
completed | Το αποτέλεσμα είναι διαθέσιμο. Αποθηκεύστε το και συγκρίνετε τις σημαντικές λεπτομέρειες με την πηγή. |
failed | Εξετάστε το failureCode. Οι αποτυχημένες εργασίες δεν χρεώνονται. Διορθώστε την αιτία και υποβάλετε την εργασία με νέο κλειδί. Η εκ νέου αποστολή του ίδιου κλειδιού επιστρέφει την ίδια αποτυχημένη εργασία. |
awaiting_payment | Η επεξεργασία ολοκληρώθηκε, αλλά το προπληρωμένο υπόλοιπο δεν επαρκούσε για τη χρέωση. Το αποτέλεσμα αποθηκεύεται, αλλά δεν παραδίδεται μέχρι να εξοφληθεί η εργασία. |
API_USER="your-api-username"
API_PASSWORD="your-api-password"
SERVICE="speech_to_text"
HOST="https://api.multi.tel"
JOB_ID=$(node -p 'JSON.parse(require("node:fs").readFileSync("speech-job.json","utf8")).data.id')
curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
"$HOST/v3/$SERVICE/$JOB_ID"Στον api.multitel.net, ορίστε το HOST σε https://api.multitel.net και διαβάστε το .response.id αντί για το .data.id.
Επαναλάβετε με ασφάλεια αιτήματα με αβέβαιη έκβαση
Αν η υποβολή λήξει λόγω υπέρβασης χρόνου ή επιστρέψει 429 ή κωδικό κατάστασης 5xx, στείλτε ξανά τα ίδια δεδομένα εισόδου με το ίδιο κλειδί ιδιοδυναμίας. Η απάντηση οποιουδήποτε από τους δύο διακομιστές μπορεί να χαθεί ή να αντικατασταθεί με σφάλμα αφού η εργασία έχει γίνει αποδεκτή. Η εκ νέου αποστολή με το ίδιο κλειδί επιστρέφει την εργασία, αν υπάρχει. Η επαναχρησιμοποίηση ενός κλειδιού με διαφορετικά δεδομένα εισόδου επιστρέφει 409 idempotency_conflict. Ορισμένα σφάλματα επαναλαμβάνονται σε κάθε προσπάθεια, όπως το 503 όταν μια υπηρεσία επί πληρωμή είναι απενεργοποιημένη ή το 500 για αρχείο ήχου που δεν μπορεί να διαβαστεί. Σταματήστε λοιπόν μετά από λίγες προσπάθειες.
Η αλλαγή κλειδιού έχει διαφορετικά αποτελέσματα για κάθε υπηρεσία.
- Για τη μετατροπή ομιλίας σε κείμενο, ένα νέο κλειδί δημιουργεί νέα εργασία με ξεχωριστή χρέωση, αν η επεξεργασία ολοκληρωθεί επιτυχώς. Το αρχικό κλειδί συνεχίζει να επιστρέφει την αρχική εργασία, ακόμη και μετά από ενημέρωση της επεξεργασίας.
- Για τη μετάφραση, ένα νέο κλειδί με πανομοιότυπο περιεχόμενο επιστρέφει μια αντίστοιχη εργασία που βρίσκεται στην ουρά, εκτελείται, έχει ολοκληρωθεί ή αναμένει πληρωμή, χωρίς νέα χρέωση. Δημιουργεί νέα εργασία αν η προηγούμενη απέτυχε ή έχει αλλάξει η έκδοση επεξεργασίας. Μια νέα προσπάθεια μετάφρασης με το αρχικό κλειδί επιστρέφει 409 μετά από αλλαγή της έκδοσης επεξεργασίας. Διατηρήστε επομένως το αρχικό αναγνωριστικό εργασίας και ανακτήστε απευθείας την εργασία.
Αποδεσμεύστε το αποτέλεσμα μετά την προσθήκη χρημάτων
Για μια εργασία σε κατάσταση awaiting_payment, προσθέστε χρήματα ώστε το υπόλοιπό σας να είναι τουλάχιστον ίσο με το costUsd της εργασίας, στρογγυλοποιημένο προς τα πάνω στο επόμενο πολλαπλάσιο του $0.00001, και κατόπιν στείλτε POST /v3/SERVICE/JOB_ID/settle. Οι χρεώσεις γίνονται σε ακέραια βήματα του $0.00001 και περιλαμβάνουν τυχόν υπόλοιπο που μεταφέρεται από προηγούμενες εργασίες της ίδιας υπηρεσίας. Έτσι, το ποσό που αφαιρείται μπορεί να υπερβαίνει το costUsd κατά λιγότερο από $0.00001. Στον api.multi.tel, στείλτε JSON {} ή κενό σώμα. Οποιαδήποτε ιδιότητα στο σώμα απορρίπτεται με 400. Ο api.multitel.net αγνοεί το σώμα. Η εξόφληση αποδεσμεύει το αποθηκευμένο αποτέλεσμα χωρίς να εκτελεί ξανά απομαγνητοφώνηση ή μετάφραση. Η απάντηση περιέχει την εργασία. Ελέγξτε ότι η κατάστασή της είναι completed. Αν το υπόλοιπο εξακολουθεί να μην επαρκεί, η εργασία παραμένει σε κατάσταση awaiting_payment και η απάντηση εξακολουθεί να έχει κωδικό HTTP 200.
Για τη μετατροπή ομιλίας σε κείμενο, η εξόφληση μιας ήδη ολοκληρωμένης εργασίας την επιστρέφει με duplicate: true, ενώ η εξόφληση μιας εργασίας που βρίσκεται στην ουρά, εκτελείται ή έχει αποτύχει επιστρέφει 409 transcription_not_awaiting_payment. Για τη μετάφραση, η εξόφληση εργασίας σε οποιαδήποτε άλλη κατάσταση επιστρέφει την εργασία αμετάβλητη. Η εξόφληση είναι διαθέσιμη μόνο όταν η επεξεργασία επί πληρωμή είναι ενεργοποιημένη (διαφορετικά 503). Οι εργασίες που αναμένουν πληρωμή υπολογίζονται ως δεσμευμένο κόστος. Για προπληρωμένους λογαριασμούς, επομένως, μπορούν να εμποδίσουν νέες υποβολές επί πληρωμή με 402 μέχρι να εξοφληθούν.
curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
-X POST -H "Content-Type: application/json" --data '{}' \
"$HOST/v3/$SERVICE/$JOB_ID/settle"Ελέγξτε τη χρήση
Χρησιμοποιήστε το GET /v3/SERVICE/usage. Οι προαιρετικές παράμετροι from και to είναι ημερομηνίες UTC σε μορφή YYYY-MM-DD και συμπεριλαμβάνονται και οι δύο οριακές ημερομηνίες. Αν παραλειφθούν, το from έχει ως προεπιλογή την ημερομηνία 30 ημέρες πριν από σήμερα και το to τη σημερινή ημερομηνία (UTC). Το to δεν πρέπει να είναι προγενέστερο του from και οι ημερομηνίες μπορούν να απέχουν το πολύ 366 ημέρες (έως 367 ημερομηνίες). Μη έγκυρες ημερολογιακές ημερομηνίες, αντίστροφο ή μεγαλύτερο εύρος επιστρέφουν 400, όπως και άλλες παράμετροι ερωτήματος στον api.multi.tel.
curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
"$HOST/v3/$SERVICE/usage?from=2026-10-01&to=2026-10-31"Η απάντηση περιέχει τα mode, currency (USD), from, to και days, μια λίστα ταξινομημένη από το νεότερο προς το παλαιότερο.
- Οι εγγραφές μετατροπής ομιλίας σε κείμενο ομαδοποιούνται ανά ημερομηνία και πηγή. Περιέχουν τα
date,source(apiήhpbxγια εγγραφές από ηχογραφήσεις του Hosted PBX),files,audioSeconds,billedSeconds,accruedUsdκαιdebitedUsd. - Οι εγγραφές μετάφρασης ομαδοποιούνται ανά ημερομηνία, πηγή και μηχανή μετάφρασης. Περιέχουν τα
date,source,engine,jobs,sourceCharacters,accruedUsdκαιdebitedUsd.
accruedUsd είναι το ακριβές κόστος με εννέα δεκαδικά ψηφία και το debitedUsd είναι το ποσό που χρεώθηκε, με πέντε. Η χρήση καταγράφεται στην ημερομηνία UTC κατά την οποία εξοφλήθηκε η χρέωση κάθε εργασίας. Επομένως, δεν εμφανίζονται εργασίες που βρίσκονται στην ουρά, εκτελούνται, απέτυχαν ή αναμένουν πληρωμή.
Όρια
Κάθε λογαριασμός μπορεί να έχει το πολύ 50 εκκρεμείς εργασίες μετατροπής ομιλίας σε κείμενο και μετάφρασης συνολικά: στην ουρά, σε εκτέλεση ή σε αναμονή πληρωμής, συμπεριλαμβανομένων των εργασιών ηχογραφήσεων του Hosted PBX. Όταν επιτευχθεί αυτό το όριο ή η συνολική χωρητικότητα της υπηρεσίας, οι υποβολές επιστρέφουν 429 transcription_queue_full ή translation_queue_full. Ο api.multi.tel περιορίζει επίσης κάθε διεύθυνση IP πελάτη σε 300 αιτήματα ανά λεπτό, για όλα τα αιτήματα προς αυτόν τον διακομιστή συνολικά. Αυτό το όριο επιστρέφει 429 με κεφαλίδες περιορισμού ρυθμού και σώμα απλού κειμένου αντί για την εξωτερική δομή σφάλματος JSON.
Χειριστείτε τα σφάλματα αιτημάτων
Στον κύριο διακομιστή, οι αποτυχίες επιστρέφουν κωδικό σφάλματος HTTP και JSON με status: "error", code, message και requestId. Κάθε απάντηση περιλαμβάνει επίσης μια κεφαλίδα X-Request-ID. Μπορείτε να δώσετε τη δική σας τιμή. Οι τιμές με μήκος πάνω από 128 χαρακτήρες περικόπτονται. Ο διακομιστής συμβατότητας επιστρέφει μόνο τον κωδικό σφάλματος στο response.code. Καταγράφετε το αναγνωριστικό αιτήματος, όπου είναι διαθέσιμο, και τον κωδικό σφάλματος, αλλά μην καταγράφετε ήχο, κείμενο ή διαπιστευτήρια στα αρχεία καταγραφής.
Συνήθεις κωδικοί κατάστασης:
| Κωδικός κατάστασης | Σημασία |
|---|---|
| 400 | Μη έγκυρα δεδομένα εισόδου. |
| 401 | Ελλιπή ή μη έγκυρα διαπιστευτήρια. |
| 402 | Ανεπαρκές προπληρωμένο υπόλοιπο. |
| 403 | Στον διακομιστή συμβατότητας, διαπιστευτήρια που δεν μπορούν να χρησιμοποιήσουν αυτές τις υπηρεσίες. |
| 404 | Άγνωστη εργασία ή διαδρομή. |
| 405 | Μη υποστηριζόμενη μέθοδος ή άγνωστη διαδρομή μέσα σε μια υπηρεσία. |
| 409 | Συγκρουόμενα δεδομένα εισόδου, μετάφραση στην ίδια γλώσσα ή εξόφληση εργασίας μετατροπής ομιλίας σε κείμενο που δεν αναμένει πληρωμή. |
| 413 | Υπερβολικά μεγάλο σώμα ή αρχείο. |
| 422 | Μη υποστηριζόμενος ήχος ή μη διαθέσιμο ζεύγος γλωσσών για τυπική μετάφραση. |
| 429 | Όρια ουράς, επικύρωσης ή ρυθμού αιτημάτων. |
| 500 | Απροσδόκητο σφάλμα διακομιστή, συμπεριλαμβανομένου αρχείου ήχου που δεν μπορεί να διαβαστεί. |
| 503 | Υπηρεσία απενεργοποιημένη ή προσωρινά μη διαθέσιμη, ή διαπιστευτήρια που δεν μπορούν να ελεγχθούν αυτήν τη στιγμή. |
Ακολουθείτε τον κωδικό σφάλματος που επιστρέφεται αντί να υποθέτετε ότι κάθε αποτυχία επικύρωσης έχει τον ίδιο κωδικό κατάστασης.
Για 429 ή 503, περιμένετε και επαναλάβετε την προσπάθεια με αυξανόμενο χρόνο αναμονής και το ίδιο κλειδί υποβολής. Τηρείτε την κεφαλίδα Retry-After όταν υπάρχει. Για μη έγκυρα δεδομένα εισόδου ή διαπιστευτήρια, διορθώστε πρώτα την αιτία. Μην υποβάλλετε επανειλημμένα νέα κλειδιά όσο προηγούμενες εργασίες παραμένουν στην ουρά.