Ugrás a főtartalomra
Magyar— Nyelv kiválasztása
Menü

A Voices API

4. lecke 14 közül Frissítve 2026. november 3. Fejlesztő
Ezen az oldalon
  1. A /v1/voices végpont
  2. Hang létrehozása
  3. Listázás, lekérés és módosítás
  4. Törlés és a minta lekérése
  5. A hangkatalógus szervezése
  6. Főbb megállapítások

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 a voxtral-mini-tts-3-0 vá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, az expressiveness beá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