Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Το API Μεταγραφής Εκτός Σύνδεσης

Μάθημα 4 / 16 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Το σημείο τελικού της μεταγραφής
  2. Παράμετροι κλήσης
  3. Υποστηριζόμενες μορφές ήχου
  4. Δομή απόκρισης
  5. Συνδυασμοί παραμέτρων
  6. Πιστοποίηση
  7. Βασικά σημεία

Το μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 για το Voxtral 3, βάσει του οδηγού Migrate from Voxtral 2 της Mistral: Τα μοντέλα Voxtral 2 (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), που απεσύρθησαν στις 31 Οκτωβρίου 2026 και θα καταργηθούν οριστικά στις 30 Απριλίου 2027, αντικαθίστανται στα παραδείγματα από τα voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 και voxtral-mini-tts-3-0. Βασικές αλλαγές: οι χρονοσημάνσεις αφορούν μόνο τμήματα (η τιμή word επιστρέφει σφάλμα 400), υποστηρίζεται η διάκριση ομιλητών σε πραγματικό χρόνο, οι ρυθμίσεις συνεδρίας πραγματικού χρόνου κλειδώνουν μετά το πρώτο κομμάτι ήχου και οι καταχωρήσεις context_bias είναι ελεύθερης μορφής (φράσεις με κενά). Πηγές: Migrate from Voxtral 2 · Speech to Text.

Το σημείο τελικού της μεταγραφής

Το API μεταγραφής εκτός σύνδεσης της Mistral χρησιμοποιεί το σημείο τελικού /audio/transcriptions. Πρόκειται για ένα σύγχρονο API: στέλνετε ένα αρχείο ήχου, το αίτημα παραμένει ανοιχτό κατά τη διάρκεια της επεξεργασίας και λαμβάνετε την πλήρη μεταγραφή στην απόκριση. Δεν υπάρχει ID εργασίας για polling ούτε webhook για διαμόρφωση. Αυτό απλοποιεί σημαντικά τον κώδικά σας, αλλά πρέπει να ορίσετε γενναιόδωρα χρονικά όρια (timeouts) για μεγάλα αρχεία.

Πριν ξεκινήσετε την κωδικοποίηση, βεβαιωθείτε ότι διαθέτετε τρεις προαπαιτούμενες προϋποθέσεις: έναν λογαριασμό στην πλατφόρμα Mistral (console.mistral.ai), ένα ενεργό κλειδί API και το Python SDK εγκατεστημένο.

Εγκατάσταση του SDK

pip install mistralai

Παράμετροι κλήσης

Όλα διαχειρίζονται μέσω της client.audio.transcriptions.complete(). Δύο παράμετροι είναι υποχρεωτικές και τέσσερις προαιρετικές. Αυτές οι προαιρετικές παράμετροι είναι που μετατρέπουν μια ακατέργαστη μεταγραφή σε ένα usable παραδοτέο.

Υποχρεωτικές παράμετροι

  • model — Το αναγνωριστικό του μοντέλου. Για μεταγραφή εκτός σύνδεσης, χρησιμοποιήστε το "voxtral-mini-transcribe-3" (συνιστάται) ή μια σταθερή έκδοση όπως το "voxtral-mini-transcribe-3".
  • file ή file_url — Το αρχείο ήχου προς μεταγραφή. Έχετε δύο επιλογές:
    • file: Ένα λεξικό {"content": file_object, "file_name": "name.mp3"} για απευθείας μεταφόρτωση.
    • file_url: Ένα δημόσιο URL που δείχνει στο αρχείο ήχου.

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

Προαιρετικές παράμετροι

Τέσσερις προαιρετικές ρυθμίσεις αλλάζουν τη φύση της εξόδου.

Το language αναμένει έναν κωδικό γλώσσας ISO, όπως "fr" ή "en", και παρακάμπτει την αυτόματη ανίχνευση. Επιβάλετέ το για ομοιογενείς παρτίδες, όπως έναν κατάλογο συνεντεύξεων που διεξήχθησαν εξ ολοκλήρου στα Γαλλικά, για να αποτρέψετε μια σύντομη αγγλόφωνη passage να αλλάξει το μοντέλο στη μέση του αρχείου. Σημειώστε ότι είναι ασυμβίβαστο με το timestamp_granularities.

Το timestamp_granularities δέχεται τη λίστα ["segment"] και ενεργοποιεί την επιστροφή χρονοσημάνσεων τμήμα προς τμήμα. Με το Voxtral 3, η κοκκομέτρεια word δεν υπάρχει πλέον και επιστρέφει σφάλμα 400. Αυτή η παράμετρος επιτρέπει αρχεία υποτίτλων συγχρονισμένα με βίντεο ή ευρετηριασμένα αποσπάσματα σε μια δίωρη διάσκεψη.

Το diarize είναι μια boolean τιμή. Όταν οριστεί σε True, το μοντέλο αναγνωρίζει τους ομιλητές και αποδίδει κάθε τμήμα σε έναν από αυτούς. Για μια εκτελεστική επιτροπή έξι ατόμων, αυτή είναι η διαφορά μεταξύ ενός ανώνυμου τοίχου κειμένου και μιας αναφοράς όπου κάθε δέσμευση είναι αποδιδόμενη.

Τέλος, το context_bias δέχεται μια λίστα όρων—μια μονή λέξη ή μια φράση με κενά, όπως ένα όνομα προϊόντος—για να βελτιώσει την αναγνώριση συγκεκριμένου λεξιλογίου. Ο αριθμός των καταχωρήσεων δεν είναι πλέον σταθερός, αλλά μοιράζονται το παράθυρο συμφραζομένων με τον ήχο, οπότε κρατήστε τη λίστα σύντομη. Μια συνάντηση μηχανικών με όρους όπως “Kubernetes” και “GDPR” γίνεται σημαντικά πιο ευανάγνωστη με αυτή τη ρύθμιση.

Υποστηριζόμενες μορφές ήχου

Το Voxtral δέχεται κοινές μορφές ήχου και σπάνια θα χρειαστεί να μετατρέψετε κάτι εκ των προτέρων. Σε περίπτωση αμφιβολίας, ανατρέξτε στη σελίδα Audio formats στην τεκμηρίωση.

ΜορφήΧαρακτηριστικό
MP3Η πιο κοινή, καλή συμπίεση
WAVΜη συμπιεσμένο, μέγιστη ποιότητα
FLACΣυμπίεση χωρίς απώλειες
OGGΑνοιχτή μορφή, καλή συμπίεση
M4A / AACΜορφή Apple, κοινή σε κινητά
WEBMΜορφή web, κοινή για εγγραφές browser

Το κρίσιμο όριο είναι το παράθυρο συμφραζομένων του μοντέλου, το οποίο μοιράζεται μεταξύ του ήχου και του λεξιλογίου context_bias. Ένα αίτημα που υπερβαίνει αυτό το όριο απορρίπτεται με σφάλμα 400· το API δεν περικόπτει το αρχείο. Για πολύ μεγάλα αρχεία, όπως ένα σεμινάριο διάρκειας μιας ημέρας, χωρίστε τα πριν την αποστολή, κατά προτίμηση σε σημεία σιωπής για να αποφύγετε την κοπή προτάσεων στη μέση.

Δομή απόκρισης

Η απόκριση περιέχει τουλάχιστον το μεταγραφόμενο κείμενο:

response.text          # Το πλήρες μεταγραφόμενο κείμενο (str)

Εάν ζητήσατε χρονοσημάνσεις (timestamp_granularities), η απόκριση περιλαμβάνει επίσης:

response.segments      # Λίστα τμημάτων με start, end, text

Εάν ενεργοποιήσατε τη διάκριση ομιλητών (diarize=True), κάθε τμήμα περιλαμβάνει την ταυτότητα του ομιλητή:

segment.speaker_id        # Αναγνωριστικό ομιλητή (str)
segment.start          # Ώρα έναρξης σε δευτερόλεπτα (float)
segment.end            # Ώρα λήξης σε δευτερόλεπτα (float)
segment.text           # Κείμενο τμήματος (str)

Εν συντομία, η μορφή του επιστρεφόμενου αντικειμένου εξαρτάται από το αίτημά σας. Κώδικας που κάνει επανάληψη στο response.segments χωρίς να περάσει το timestamp_granularities θα αποτύχει. Επαληθεύετε πάντα τη συνοχή μεταξύ των παραμέτρων εισόδου και του χειρισμού της εξόδου σας.

Συνδυασμοί παραμέτρων

Ακολουθούν οι πέντε έγκυροι συνδυασμοί που θα συναντήσετε συχνότερα, από τον απλούστερο στον πιο εξειδικευμένο.

# Απλή μεταγραφή (μόνο κείμενο)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"}
)

# Με επιβεβλημένη γλώσσα (χωρίς χρονοσημάνσεις)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Με χρονοσημάνσεις τμημάτων
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Με διάκριση ομιλητών + χρονοσημάνσεις
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Με προκατάληψη συμφραζομένων (context biasing)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/audio.mp3",
    context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)

Μια εκπληκτική περιοριστική συνθήκη στο Voxtral 2 ήταν ότι τα language και timestamp_granularities δεν μπορούσαν να χρησιμοποιηθούν μαζί στην ίδια κλήση. Η τεκμηρίωση του Voxtral 3 δεν αναφέρει πλέον αυτόν τον περιορισμό· επαληθεύστε το με ένα τεστ πριν βασιστείτε σε αυτό.

Πιστοποίηση

Όλα τα αιτήματα απαιτούν ένα έγκυρο κλειδί API που περνάει στον κατασκευαστή του client. Στην ανάπτυξη, ένα άμεσο όρισμα αρκεί. Στην παραγωγή, χρησιμοποιήστε μια μεταβλητή περιβάλλοντος για να αποτρέψετε την καταχώρηση του κλειδιού στο αποθετήριο Git σας.

from mistralai.client import Mistral

# Μέσω άμεσου ορίσματος
client = Mistral(api_key="your-api-key")

# Ή μέσω μεταβλητής περιβάλλοντος (συνιστάται για παραγωγή)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Βασικά σημεία

  • Το σημείο τελικού /audio/transcriptions είναι σύγχρονο: στείλτε το αρχείο, λάβετε το κείμενο.
  • Δύο λειτουργίες μεταφόρτωσης: απευθείας μεταφόρτωση (file) ή δημόσιο URL (file_url).
  • Προαιρετικές παράμετροι: language, timestamp_granularities, diarize, context_bias.
  • Στο Voxtral 2, τα language και timestamp_granularities ήταν αμοιβαία αποκλειόμενα· η τεκμηρίωση του Voxtral 3 δεν το αναφέρει πλέον αυτό.
  • Υποστηρίζονται κοινές μορφές ήχου· το όριο είναι το παράθυρο συμφραζομένων που μοιράζεται ο ήχος και το context_bias (σφάλμα 400 εάν υπερβεί).
  • Η διάκριση ομιλητών και οι χρονοσημάνσεις μπορούν να συνδυαστούν.