API μεταγραφής ήχου

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

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

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

Στον api.multi.tel, κάθε διαδρομή είναι επίσης διαθέσιμη με το πρόθεμα /v1/speech-to-text αντί του /v3/speech_to_text, για παράδειγμα POST /v1/speech-to-text/estimate. Στον api.multitel.net, χρησιμοποιήστε τις διαδρομές /v3/speech_to_text.

Η απάντηση πληροφοριών υπηρεσίας αναφέρει τα mode (batch), realtime (false), paidEnabled (αν γίνονται δεκτές νέες επί πληρωμή υποβολές αυτή τη στιγμή), pricePerMinuteUsd (0.005), billingUnit (audio_second), maxAudioSeconds (7200) και maxUploadBytes (26214400), μαζί με μια σύντομη description. Η ανάκτησή της είναι δωρεάν και λειτουργεί όταν οι επί πληρωμή υποβολές είναι απενεργοποιημένες· επιστρέφει 503 transcription_unavailable μόνο όταν ολόκληρη η υπηρεσία δεν είναι διαθέσιμη.

Προετοιμασία αρχείου ήχου

Χρησιμοποιήστε ολοκληρωμένο αρχείο ήχου έως 25 MiB (26,214,400 bytes) και διάρκειας έως 2 ώρες (7,200 δευτερόλεπτα). Κατά την υποβολή, το αρχείο πρέπει να αναγνωρίζεται ως μέσο MP3, WAV, Ogg, FLAC, MOV ή Matroska που περιέχει ροή ήχου, με διάρκεια στα μεταδεδομένα μεγαλύτερη από μηδέν και όχι πάνω από 7,200 δευτερόλεπτα. Ένα αναγνωρισμένο αρχείο που δεν περνά αυτούς τους ελέγχους απορρίπτεται με 422 unsupported_audio. Ένα αρχείο που δεν μπορεί να διαβαστεί ως κάποια από αυτές τις μορφές μπορεί προς το παρόν να απορριφθεί με σφάλμα διακομιστή (500)· μην υποβάλετε ξανά το ίδιο αρχείο χωρίς αλλαγές. Η επέκταση αρχείου από μόνη της δεν αποδεικνύει συμβατότητα.

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

Η προαιρετική ένδειξη γλώσσας είναι ένας κωδικός δύο ή τριών πεζών γραμμάτων για την ομιλούμενη γλώσσα, όπως en. Για να μη δώσετε ένδειξη, παραλείψτε το πεδίο· ο api.multi.tel απορρίπτει την κενή συμβολοσειρά. Η ένδειξη καθοδηγεί την επεξεργασία, αλλά δεν ελέγχεται σε λίστα υποστηριζόμενων γλωσσών, οπότε χρησιμοποιήστε έγκυρο κωδικό για την ομιλούμενη γλώσσα.

Υποβολή εργασίας μεταγραφής

Στείλτε JSON με Content-Type: application/json στο POST https://api.multi.tel/v3/speech_to_text. Το σώμα αιτήματος μπορεί να φτάνει τα 35 MiB, ώστε να χωρά αρχείο μέγιστου μεγέθους μετά την κωδικοποίηση base64· μεγαλύτερο σώμα απορρίπτεται με 413.

Οποιαδήποτε άλλη ιδιότητα JSON, συμπεριλαμβανομένης της idempotency_key, απορρίπτεται με 400 invalid_transcription_request. Στείλτε το κλειδί ως κεφαλίδα.

Κλειδί ιδιοδυναμίας

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

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

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

node -e 'process.stdout.write(JSON.stringify({audioBase64:require("node:fs").readFileSync("completed-call.mp3").toString("base64"),language:"en"}))' > completed-call.json

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: speech-call-001" \
  --data-binary @completed-call.json \
  -o speech-job.json \
  https://api.multi.tel/v3/speech_to_text

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

Μια νέα εργασία επιστρέφει HTTP 202 με τα παρακάτω πεδία, ενώ η επανάληψη επιστρέφει HTTP 200 με το πλήρες αντικείμενο εργασίας που περιγράφεται στην ενότητα Ανάγνωση της μεταγραφής. Διαβάστε το αναγνωριστικό εργασίας, ένα UUID, από το data.id. Η απάντηση νέας εργασίας έχει την ακόλουθη μορφή (το αναγνωριστικό και οι τιμές είναι παραδείγματα):

{
  "status": "success",
  "data": {
    "id": "3f6c1b2e-8a4d-4e7f-9c21-5b0d7e4a9f13",
    "status": "queued",
    "mode": "batch",
    "realtime": false,
    "source": "api",
    "durationSeconds": 90.5,
    "billedSeconds": 91,
    "costUsd": "0.007583334",
    "pricePerMinuteUsd": "0.005"
  }
}

Όσο μια εργασία βρίσκεται στην ουρά ή εκτελείται, τα durationSeconds, billedSeconds και costUsd είναι εκτιμήσεις από τα μεταδεδομένα του αρχείου. Η τελική χρέωση χρησιμοποιεί την αποκωδικοποιημένη διάρκεια.

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

Εκτίμηση χωρίς δημιουργία εργασίας

Στείλτε το ίδιο σώμα JSON στο POST https://api.multi.tel/v3/speech_to_text/estimate. Δεν απαιτείται κλειδί ιδιοδυναμίας. Η εκτίμηση επικυρώνει και μετρά το αρχείο, αλλά δεν το μεταγράφει, δεν δημιουργεί εργασία, δεν δεσμεύει χρήματα, δεν ελέγχει το υπόλοιπο και δεν χρεώνει τον λογαριασμό. Μια ένδειξη language γίνεται δεκτή, αλλά δεν επηρεάζει την εκτίμηση.

Μια επιτυχής εκτίμηση επιστρέφει HTTP 200 με estimate: true, charged: false, mode, realtime, durationSeconds, billedSeconds, pricePerMinuteUsd και costUsd μέσα στο data. Χρησιμοποιεί τη διάρκεια στα μεταδεδομένα του αρχείου, ενώ μια ολοκληρωμένη εργασία χρεώνεται βάσει της αποκωδικοποιημένης διάρκειας, η οποία μπορεί να διαφέρει. Οι εκτιμήσεις εφαρμόζουν τους ίδιους ελέγχους αρχείων με τις υποβολές. Είναι διαθέσιμες μόνο όταν η επί πληρωμή μεταγραφή είναι ενεργοποιημένη (διαφορετικά 503 paid_transcription_not_enabled). Μπορούν να επιστρέψουν 429 audio_validation_busy όταν η επικύρωση αρχείων έχει φτάσει τη μέγιστη χωρητικότητά της· δοκιμάστε ξανά ύστερα από σύντομη αναμονή.

Ανάγνωση της μεταγραφής

Ελέγχετε περιοδικά το GET /v3/speech_to_text/JOB_ID όπως περιγράφεται στον οδηγό ροής εργασιών. Το αντικείμενο εργασίας περιέχει τα εξής πεδία:

Οι μεταγραφές, οι χρονικές σημάνσεις και οι ετικέτες γλώσσας και καναλιού παράγονται αυτόματα και η ακρίβειά τους δεν είναι εγγυημένη. Κάθε ένδειξη ποιότητας είναι λόγος να ελέγξετε το αποτέλεσμα και να συγκρίνετε σημαντικά ονόματα, αριθμούς και δεσμεύσεις με τον αρχικό ήχο. Οι μεγάλες σιωπές και τα πολύ σιγανά αποσπάσματα παραλείπονται και δεν παράγουν τμήματα. Τα αποτελέσματα δεν αναγνωρίζουν μεμονωμένους ομιλητές. Όταν ένα αποτέλεσμα αναφέρει channelCount ίσο με 2, κάθε τμήμα έχει channel ίσο με A (το πρώτο ή αριστερό κανάλι) ή B (το δεύτερο ή δεξί κανάλι). Αυτό διαχωρίζει τους ομιλητές μόνο όταν καθένας έχει ηχογραφηθεί σε διαφορετικό κανάλι. Ο ήχος δύο καναλιών χρεώνεται μία φορά βάσει της συνολικής διάρκειάς του, όχι ανά κανάλι. Τα μονοφωνικά αποτελέσματα δεν έχουν ετικέτες καναλιού.

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

Το σημείο πρόσβασης συμβατότητας POST https://api.multitel.net/v3/speech_to_text δέχεται multipart/form-data με ένα μέρος αρχείου audio και προαιρετικό πεδίο language, αντί για JSON audioBase64. Μια κενή τιμή language αντιμετωπίζεται ως απουσία ένδειξης. Στείλτε την ίδια κεφαλίδα Idempotency-Key. Αν λείπει η κεφαλίδα, αυτός ο διακομιστής δέχεται επίσης πεδίο φόρμας idempotency_key. Πεδία με όνομα source, free, billing_source, realtime ή stream απορρίπτονται με 400 unsupported_transcription_option· τα άλλα πεδία της φόρμας αγνοούνται. Ο διακομιστής επιστρέφει επίσης τα εξής σφάλματα:

• 400 idempotency_key_required για κλειδί που λείπει ή είναι υπερβολικά μεγάλο.
• 400 audio_upload_required για μεταφόρτωση που λείπει ή δεν παραλήφθηκε πλήρως.
• 400 invalid_language για μη έγκυρη γλώσσα.
• 413 invalid_audio_size για κενό ή υπερβολικά μεγάλο αρχείο.
• 400 invalid_job για αναγνωριστικό εργασίας με λανθασμένη μορφή.

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

Για εκτίμηση σε αυτόν τον διακομιστή, στείλτε με POST τα ίδια multipart πεδία στο /v3/speech_to_text/estimate. Δεν απαιτείται κλειδί ιδιοδυναμίας και η εκτίμηση βρίσκεται μέσα στο response.

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

curl --fail-with-body --silent --show-error --user "$API_USER:$API_PASSWORD" \
  -H "Idempotency-Key: speech-call-001" \
  -F "audio=@completed-call.mp3" -F "language=en" \
  -o speech-job.json \
  https://api.multitel.net/v3/speech_to_text

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