A Voices API
Ezen az oldalon
A tanfolyam frissítve: 2026. november 3., Voxtral TTS 3 verzióhoz, a Migrálás a Voxtral 2-ről útmutató és a Mistral Szövegből beszéd oldalai alapján: a
voxtral-mini-tts-2603, amelyet 2026. október 31-én elavulttá nyilvánítottak és 2027. április 30-án eltávolítanak, a példákban avoxtral-mini-tts-3-0váltja fel. A Voxtral 2 előre definiált hangjai (gb_jane_neutral…) továbbra is elfogadottak; a Voxtral 3 hozzáadja a[emotion=…]és[pace=…]címkéket a szövegben, azexpressivenessbeállítást, az egyéni kiejtést (phoneme_hints) és 35 nyelvet támogat. A Mistral ajánlja a késleltetés újbóli mérését a migrálás után. Források: Migrálás a Voxtral 2-ről · Beszédgenerálás.
A /v1/voices végpont
A Mistral Voices API a belépési pontod az egyedi hangok kezeléséhez. Teljes CRUD műveletkészletet (Create, Read, Update, Delete) tesz elérhetővé, lehetővé téve hangok létrehozását, listázását, lekérését, módosítását és törlését. Ha dolgoztál már szabványos REST API-val, ismerős terepen jársz: itt semmi nem foglalkozik közvetlenül a hangfeldolgozással; ez kizárólag egy objektumkatalógus kezeléséről szól.
Minden API-n keresztül létrehozott hang egy egyedi azonosítót kap, a voice_id-t, amelyet később a beszédgeneráláshoz használsz. Jegyezd meg: a hangok maradandóak. Létrehozásuk után elérhetők maradnak a fiókodban, amíg kifejezetten nem törlöd őket. Nem kell minden generálásnál újra elküldened a hangmintát, így alkalmazásaidnak csak egy karakterláncot kell tárolniuk a konfigurációjukban.
Hang létrehozása
A létrehozás egy POST hívással történik a /v1/voices végpontra. Base64 kódolású hangmintát és leíró metaadatokat kell megadnod:
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Hangminta kódolása base64-re
sample_audio_b64 = base64.b64encode(
Path("sample.mp3").read_bytes()
).decode()
# Hang létrehozása
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}")
A base64 használata szükséges, mert a kérés egy JSON dokumentum, a JSON pedig nem képes bináris adatokat szállítani. Az API egy objektumot ad vissza, amely tartalmazza a voice_id-t; ezt meg kell őrizned minden generálási kéréshez. A fenti példában csak kiírjuk, de éles környezetben írd ki a konfigurációs fájlodba vagy az adatbázisodba.
Listázás, lekérés és módosítás
Az összes hangod listájának lekéréséhez a list() módszer támogatja a lapozást:
# Az első 10 hang lekérése
voices = client.audio.voices.list(limit=10, offset=0)
for v in voices.items:
print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")
A lapozás eltoláson (offset) alapul: a limit paraméterrel adod meg az elemek számát, az offset-tel pedig a kezdőpontot. A Mistral előre definiált hangjainak (pl. Marie franciául, fr_marie_neutral, Jane brit angolul stb.) böngészéséhez a voices.search mindkét családot listázza, amelyeket a type mező különböztet meg: preset vagy custom. A tíz hangból álló második oldal lekéréséhez hívd meg a módszert offset=10 értékkel. Ez a mechanizmus akkor válik hasznossá, amikor egy ügynökség ügyfelek tucatjai számára kezel hangokat.
Ha egy adott hang részleteire van szükséged, a get() visszaadja a teljes metaadatokat:
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}")
Szoktasd rá magad, hogy egy nagyobb generálási futtatás előtt meghívod ezt a műveletet. Ezzel ellenőrizheted, hogy az alkalmazásodba hardcoded voice_id a várt hangra mutat, és nem egy régi projektből származóra.
Módosíthatod egy meglévő hang metaadatait anélkül, hogy hozzáérnél a hangmintához:
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}")
Módosítható mezők: name, languages, gender, age, tags és description. Az eredeti hangminta azonban nem módosítható. Ha meg akarod változtatni a hangot, új hangot kell létrehoznod. A gyakorlatban egy rosszul felvett hang nem javítható – le kell cserélni, és az új voice_id-t propagálnod kell az alkalmazásaidban.
Törlés és a minta lekérése
A törlés végleges és visszafordíthatatlan:
client.audio.voices.delete(voice_id="your-voice-id")
print("Voice deleted")
Törlés után minden olyan generálási kérés, amely ezt a voice_id-t használja, sikertelen lesz. Egy klasszikus rémálom-szcenárió: egy fejlesztő takarításképpen törli a teszthangokat, véletlenül töröl egyet, ami valójában az ügyfélszolgálati IVR-t hajtja, és az incidens másnap reggel, az első bejövő híváskor robban ki. Mindig győződj meg róla, hogy alkalmazásaid frissültek, mielőtt éles környezetben törölnél egy hangot.
Le is töltheted a hang létrehozásához használt eredeti audiót:
response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)
Ez a funkció segít archiválni a mintáidat, vagy ellenőrizni a forrásaudió minőségét, ha egy hang csalódást okoz. Az eredeti meghallgatásával gyakran rájöhetsz, hogy a generálás során hallott hiba már a felvételben is jelen volt.
A hangkatalógus szervezése
A tiszta menedzsment kevesebbe kerül, és jelentős zavart előz meg. Nevezd el egyértelműen a hangjaidat projekt előtaggal, követve olyan mintákat, mint a podcast-narrator vagy app-assistant-fr, ne pedig a voice1 és test-final-2 neveket. Használj címkéket a használati eset, projekt vagy ügyfél szerinti kategorizáláshoz, így a listák kezelhetőek maradnak bővülésük során. Dokumentáld a voice_id-ket az alkalmazásod konfigurációjában, soha ne egy elszigetelt fájlban egy munkállomáson. És soha ne törölj éles hangot anélkül, hogy előtte ellenőrizted volna: sehol sem hivatkoznak már rá.
Főbb megállapítások
- A Voices API teljes CRUD képességeket tesz elérhetővé: létrehozás, listázás, lekérés, frissítés, törlés
- Minden hang egy egyedi
voice_id-t kap, amelyet a generálási kérésekben használsz - Az eltoláson alapuló lapozás lehetővé teszi nagy számú hang kezelését
- A törlés végleges – minden ezzel a voice_id-val indított kérés sikertelen lesz
- Az eredeti hangminta lekérhető a sample végponton keresztül