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

Το API Φωνών (Voices API)

Μάθημα 4 / 14 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Το Endpoint /v1/voices
  2. Δημιουργία Φωνής
  3. Απαρίθμηση, Ανάκτηση και Τροποποίηση
  4. Διαγραφή και Ανάκτηση του Δείγματος
  5. Οργάνωση του Καταλόγου Φωνών σας
  6. Βασικά σημεία

Το μάθημα ενημερώθηκε στις 3 Νοεμβρίου 2026 για το Voxtral TTS 3, με βάση τον οδηγό Migrate from Voxtral 2 και τις σελίδες Text to Speech της Mistral: το voxtral-mini-tts-2603, που αποσύρθηκε στις 31 Οκτωβρίου 2026 και θα αφαιρεθεί στις 30 Απριλίου 2027, αντικαθίσταται στα παραδείγματα από το voxtral-mini-tts-3-0. Οι προκαθορισμένες φωνές του Voxtral 2 (gb_jane_neutral…) γίνονται δεκτές· το Voxtral 3 προσθέτει ετικέτες [emotion=…] και [pace=…] στο κείμενο, τη ρύθμιση expressiveness, προσαρμοσμένη προφορά (phoneme_hints) και 35 γλώσσες. Η Mistral συνιστά επαναμέτρηση του λανθάνοντος χρόνου (latency) μετά τη μετάβαση. Πηγές: Migrate from Voxtral 2 · Speech generation.

Το Endpoint /v1/voices

Το API Φωνών (Voices API) της Mistral αποτελεί το σημείο εισόδου σας για τη διαχείριση προσαρμοσμένων φωνών. Εκθέτει ένα πλήρες σύνολο λειτουργιών CRUD—Create, Read, Update, Delete—επιτρέποντάς σας να δημιουργείτε, να απαριθμείτε, να ανακτάτε, να τροποποιείτε και να διαγράφετε φωνές. Εάν έχετε εργαστεί στο παρελθόν με ένα τυπικό REST API, βρίσκεστε σε οικείο έδαφος: τίποτα εδώ δεν αφορά άμεσα την επεξεργασία ήχου· πρόκειται αποκλειστικά για τη διαχείριση ενός καταλόγου αντικειμένων.

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

Δημιουργία Φωνής

Η δημιουργία πραγματοποιείται μέσω μιας κλήσης POST στο endpoint /v1/voices. Παρέχετε ένα δείγμα ήχου κωδικοποιημένο σε base64 μαζί με περιγραφικά μεταδεδομένα:

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Encode the audio sample to base64
sample_audio_b64 = base64.b64encode(
    Path("sample.mp3").read_bytes()
).decode()

# Create the voice
voice = client.audio.voices.create(
    name="my-pro-voice",
    sample_audio=sample_audio_b64,
    sample_filename="sample.mp3",
    languages=["fr", "en"],
    gender="female",
    age=35,
    tags=["professional", "podcast"]
)

print(f"Voice created: {voice.id}")

Η χρήση του base64 είναι απαραίτητη επειδή το αίτημα είναι ένα έγγραφο JSON και το JSON δεν μπορεί να μεταφέρει δυαδικά δεδομένα. Το API επιστρέφει ένα αντικείμενο που περιέχει το voice_id το οποίο θα διατηρήσετε για όλα τα αιτήματα δημιουργίας. Στο παραπάνω παράδειγμα, το εκτυπώνουμε, αλλά σε περιβάλλον παραγωγής θα πρέπει να το εγγράψετε στη διαμόρφωση ή τη βάση δεδομένων σας.

Απαρίθμηση, Ανάκτηση και Τροποποίηση

Για να ανακτήσετε μια λίστα με όλες τις φωνές σας, η μέθοδος list() υποστηρίζει σελιδοποίηση:

# Get the first 10 voices
voices = client.audio.voices.list(limit=10, offset=0)

for v in voices.items:
    print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")

Η σελιδοποίηση βασίζεται σε μετατόπιση (offset-based): καθορίζετε τον αριθμό των στοιχείων με το limit και το σημείο εκκίνησης με το offset. Για να περιηγηθείτε και στις προκαθορισμένες φωνές της Mistral (όπως η Marie στα Γαλλικά, fr_marie_neutral, η Jane στα Βρετανικά Αγγλικά κ.λπ.), το voices.search απαριθμεί και τις δύο οικογένειες, οι οποίες διακρίνονται από το πεδίο type: preset ή custom. Για να λάβετε τη δεύτερη σελίδα με δέκα φωνές, καλείτε τη μέθοδο με offset=10. Αυτός ο μηχανισμός καθίσταται χρήσιμος μόλις ένας οργανισμός διαχειρίζεται φωνές για δεκάδες πελάτες.

Όταν χρειάζεστε λεπτομέρειες για μια συγκεκριμένη φωνή, η get() επιστρέφει όλα τα μεταδεδομένα της:

voice = client.audio.voices.get(voice_id="your-voice-id")

print(f"Name: {voice.name}")
print(f"Gender: {voice.gender}")
print(f"Languages: {voice.languages}")
print(f"Tags: {voice.tags}")

Κάντε συνήθεια να καλείτε αυτή τη λειτουργία πριν από μια μεγάλη εκτέλεση δημιουργίας. Αυτό επαληθεύει ότι το voice_id που είναι ενσωματωμένο στην εφαρμογή σας δείχνει στην αναμενόμενη φωνή και όχι σε μία από ένα παλιό έργο.

Μπορείτε να τροποποιήσετε τα μεταδεδομένα μιας υπάρχουσας φωνής χωρίς να αγγίξετε το δείγμα ήχου:

updated_voice = client.audio.voices.update(
    voice_id="your-voice-id",
    name="my-pro-voice-v2",
    languages=["fr", "en", "es"],
    tags=["professional", "podcast", "multilingual"]
)

print(f"Voice updated: {updated_voice.name}")

Τα πεδία που μπορούν να τροποποιηθούν περιλαμβάνουν τα name, languages, gender, age, tags και description. Το αρχικό δείγμα ήχου, ωστόσο, δεν μπορεί να τροποποιηθεί. Εάν θέλετε να αλλάξετε τον ήχο, πρέπει να δημιουργήσετε μια νέα φωνή. Στην πράξη, μια φωνή με κακή ηχογράφηση δεν μπορεί να επιδιορθωθεί· πρέπει να αντικατασταθεί και θα χρειαστεί να διαδώσετε το νέο voice_id σε όλες τις εφαρμογές σας.

Διαγραφή και Ανάκτηση του Δείγματος

Η διαγραφή είναι οριστική και μη αναστρέψιμη:

client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")

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

Μπορείτε επίσης να κατεβάσετε τον αρχικό ήχο που χρησιμοποιήθηκε για τη δημιουργία μιας φωνής:

response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)

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

Οργάνωση του Καταλόγου Φωνών σας

Η καθαρή διαχείριση κοστίζει ελάχιστα και αποτρέπει σημαντική σύγχυση. Ονομάζετε τις φωνές σας με σαφήνεια χρησιμοποιώντας ένα πρόθεμα έργου, ακολουθώντας μοτίβα όπως podcast-narrator ή app-assistant-fr, αντί για voice1 και test-final-2. Χρησιμοποιείτε ετικέτες (tags) για κατηγοριοποίηση ανά περίπτωση χρήσης, έργο ή πελάτη, καθιστώντας τις λίστες διαχειρίσιμες καθώς μεγαλώνουν. Τεκμηριώνετε τα voice_id στη διαμόρφωση της εφαρμογής σας και ποτέ σε ένα μεμονωμένο αρχείο σε έναν σταθμό εργασίας. Και μην διαγράφετε ποτέ μια φωνή παραγωγής χωρίς πρώτα να επαληθεύσετε ότι δεν αναφέρεται πλέον πουθενά.

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

  • Το API Φωνών εκθέτει πλήρεις δυνατότητες CRUD: δημιουργία, απαρίθμηση, ανάκτηση, ενημέρωση, διαγραφή
  • Κάθε φωνή λαμβάνει ένα μοναδικό voice_id που χρησιμοποιείται στα αιτήματα δημιουργίας
  • Η σελιδοποίηση βάσει μετατόπισης (offset-based) σας επιτρέπει να διαχειρίζεστε μεγάλο αριθμό φωνών
  • Η διαγραφή είναι οριστική· όλα τα αιτήματα που χρησιμοποιούν αυτό το voice_id θα αποτύχουν
  • Το αρχικό δείγμα ήχου μπορεί να ανακτηθεί μέσω του endpoint του δείγματος