API-ul Voices
Pe această pagină
Curs actualizat la 3 noiembrie 2026 pentru Voxtral TTS 3, pe baza ghidului Migrate from Voxtral 2 și a paginilor Mistral dedicate Text to Speech:
voxtral-mini-tts-2603, depreciat la 31 octombrie 2026 și eliminat la 30 aprilie 2027, este înlocuit în exemple prinvoxtral-mini-tts-3-0. Vocile predefinite din Voxtral 2 (gb_jane_neutral…) rămân acceptate; Voxtral 3 adaugă etichetele[emotion=…]și[pace=…]în text, setareaexpressiveness, pronunția personalizată (phoneme_hints) și suport pentru 35 de limbi. Mistral recomandă reevaluarea latenței după migrare. Surse: Migrate from Voxtral 2 · Speech generation.
Endpoint-ul /v1/voices
API-ul Voices de la Mistral este punctul dumneavoastră de intrare pentru gestionarea vocilor personalizate. Acesta expune un set complet de operațiuni CRUD (Create, Read, Update, Delete), permițându-vă să creați, listați, recuperați, modificați și ștergeți voci. Dacă ați lucrat anterior cu un API REST standard, vă veți simți ca acasă: nimic aici nu procesează direct audio; este vorba exclusiv despre gestionarea unui catalog de obiecte.
Fiecare voce creată prin API primește un identificator unic, voice_id, pe care îl veți utiliza ulterior pentru a genera vorbire. Rețineți acest aspect: vocile sunt persistente. Odată create, ele rămân disponibile în contul dumneavoastră până la ștergerea lor explicită. Nu este nevoie să retrimiteți eșantionul audio pentru fiecare generare, astfel încât aplicațiile dumneavoastră trebuie doar să stocheze un șir de caractere în configurație.
Crearea unei voci
Crearea se realizează printr-un apel POST către endpoint-ul /v1/voices. Furnizați un eșantion audio codificat în base64 împreună cu metadatele descriptive:
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}")
Utilizarea base64 este necesară deoarece cererea este un document JSON, iar JSON nu poate transporta date binare. API-ul returnează un obiect care conține voice_id pe care îl veți păstra pentru toate cererile de generare. În exemplul de mai sus, îl afișăm, dar în producție ar trebui să îl scrieți în configurația sau baza de date a aplicației dumneavoastră.
Listarea, recuperarea și modificarea
Pentru a obține o listă a tuturor vocilor dumneavoastră, metoda list() suportă paginare:
# 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})")
Paginarea se bazează pe deplasare (offset): specificați numărul de elemente prin limit și punctul de plecare prin offset. Pentru a lista și vocile predefinite de la Mistral (Marie în franceză, fr_marie_neutral, Jane în engleza britanică etc.), voices.search listează ambele familii, distinse prin câmpul type: preset sau custom. Pentru a obține a doua pagină de zece voci, apelați metoda cu offset=10. Acest mecanism devine util imediat ce o agenție gestionează voci pentru zeci de clienți.
Când aveți nevoie de detalii despre o voce specifică, get() returnează toate metadatele sale:
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}")
Obișnuiți-vă să apelați această operațiune înainte de o rulare majoră de generare. Astfel verificați dacă voice_id hardcoded în aplicația dumneavoastră indică vocea așteptată și nu una dintr-un proiect vechi.
Puteți modifica metadatele unei voci existente fără a atinge eșantionul audio:
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}")
Câmpurile modificabile includ name, languages, gender, age, tags și description. Eșantionul audio original, însă, nu poate fi modificat. Dacă doriți să schimbați audio-ul, trebuie să creați o voce nouă. În practică, o voce înregistrată prost nu poate fi reparată – trebuie înlocuită, iar dumneavoastră va trebui să propagați noul voice_id în toate aplicațiile dumneavoastră.
Ștergerea și recuperarea eșantionului
Ștergerea este permanentă și ireversibilă:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
După ștergere, orice cerere de generare care utilizează acel voice_id va eșua. Un scenariu coșmar clasic: un dezvoltator curăță vocile de test, șterge din greșeală una care alimentează de fapt IVR-ul de suport, iar incidentul izbucnește a doua dimineață la primul apel primit. Asigurați-vă întotdeauna că aplicațiile dumneavoastră sunt actualizate înainte de a șterge o voce în producție.
De asemenea, puteți descărca audio-ul original utilizat pentru a crea o voce:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Această funcționalitate vă ajută să vă arhivați eșantioanele sau să verificați calitatea audio-ului sursă dacă o voce vă dezamăgește. Ascultând originalul, descoperiți adesea că defectul auzit în timpul generării era deja prezent în înregistrare.
Organizarea catalogului de voci
O gestionare curată costă puțin și previne confuzii majore. Denumiți-vă vocile clar, cu un prefix de proiect, urmând modele precum podcast-narrator sau app-assistant-fr, în loc de voice1 și test-final-2. Utilizați etichete (tags) pentru a categorisi după caz de utilizare, proiect sau client, făcând listele ușor de gestionat pe măsură ce cresc. Documentați voice_id-urile în configurația aplicației dumneavoastră, niciodată într-un fișier izolat pe o stație de lucru. Și nu ștergeți niciodată o voce de producție fără a verifica mai întâi că nu mai este referențiată nicăieri.
Puncte cheie
- API-ul Voices expune capacități CRUD complete: creare, listare, recuperare, actualizare, ștergere
- Fiecare voce primește un
voice_idunic utilizat în cererile de generare - Paginarea bazată pe offset vă permite să gestionați un număr mare de voci
- Ștergerea este permanentă – toate cererile care utilizează acel voice_id vor eșua
- Eșantionul audio original poate fi recuperat prin endpoint-ul dedicat