Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

L-API tal-Vuċijiet

Lezzjoni 4 / 14 Aġġornat 3 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. L-Endpoint /v1/voices
  2. Ħolqien ta’ Vuċi
  3. Elenkar, Rikupru u Modifika
  4. Tħassir u Rikupru tal-Kampjun
  5. Organizzazzjoni tal-Katalogu tal-Vuċijiet Tiegħek
  6. Punti Ewlenin

Kors aġġornat fit-3 ta’ Novembru 2026 għal Voxtral TTS 3, ibbażat fuq il-gwida Migrate from Voxtral 2 u l-paġni Text to Speech ta’ Mistral: voxtral-mini-tts-2603, deprekat fil-31 ta’ Ottubru 2026 u mneħħi fit-30 ta’ April 2027, huwa sostitwit fl-eżempji b’voxtral-mini-tts-3-0. Il-vuċijiet predefiniti ta’ Voxtral 2 (gb_jane_neutral…) jibqgħu aċċettati; Voxtral 3 iżid it-tags [emotion=…] u [pace=…] fit-test, is-setting expressiveness, il-pronunzja personalizzata (phoneme_hints), u 35 lingwa. Mistral jirrakkomanda li terġa’ tkejjel il-latency wara l-migrazzjoni. Sorsi: Migrate from Voxtral 2 · Speech generation.

L-Endpoint /v1/voices

L-API tal-Vuċijiet ta’ Mistral hija l-punt tad-dħul tiegħek għall-ġestjoni ta’ vuċijiet personalizzati. Tesponi sett sħiħ ta’ operazzjonijiet CRUD—Create, Read, Update, Delete—li jħalluk toħloq, telenka, tirrikupra, timmodifika u tħassar vuċijiet. Jekk qatt ħdimt ma’ API REST standard qabel, inti fuq art familjari: xejn hawnhekk ma jittratta direttament l-ipproċessar tal-awdjo; dan huwa purament dwar il-ġestjoni ta’ katalogu ta’ oġġetti.

Kull vuċi maħluqa permezz tal-API tirċievi identifikatur uniku, il-voice_id, li se tuża aktar tard biex tiġġenera kliem. Żomm dan f’moħħok: il-vuċijiet huma persistenti. Darba maħluqa, jibqgħu disponibbli fil-kont tiegħek sakemm jitħassru b’mod espliċitu. M’għandekx bżonn tibgħat mill-ġdid il-kampjun tal-awdjo għal kull ġenerazzjoni, allura l-applikazzjonijiet tiegħek għandhom bżonn biss jaħżnu string fil-konfigurazzjoni tagħhom.

Ħolqien ta’ Vuċi

Il-ħolqien iseħħ permezz ta’ sejħa POST lejn l-endpoint /v1/voices. Tipprovdi kampjun tal-awdjo kodifikat f’base64 flimkien ma’ metadata deskrittiva:

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}")

L-użu ta’ base64 huwa meħtieġ għax it-talba hija dokument JSON, u JSON ma jistax iġorr data binarja. L-API tirritorna oġġett li fih il-voice_id li se żżomm għat-talbiet kollha ta’ ġenerazzjoni. Fl-eżempju ta’ hawn fuq, aħna nistampawh, iżda fil-produzzjoni għandek tiktbu fil-konfigurazzjoni jew fil-bażi tad-data tiegħek.

Elenkar, Rikupru u Modifika

Biex tirrikupra lista tal-vuċijiet kollha tiegħek, il-metodu list() jappoġġja l-paġinazzjoni:

# 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})")

Il-paġinazzjoni hija ibbażata fuq l-offset: tispeċifika n-numru ta’ oġġetti b’limit u l-punt tat-tluq b’offset. Biex tibbrawżja wkoll il-vuċijiet predefiniti ta’ Mistral (Marie bil-Franċiż, fr_marie_neutral, Jane bl-Ingliż Brittaniku, eċċ.), voices.search jelenka ż-żewġ familji, distinti mill-qasam type: preset jew custom. Biex tikseb it-tieni paġna ta’ għaxar vuċijiet, isejjaħ il-metodu b’offset=10. Dan il-mekkaniżmu jsir utli malli aġenzija timmaniġġja vuċijiet għal għexieren ta’ klijenti.

Meta jkollok bżonn dettalji fuq vuċi speċifika, get() tirritorna l-metadata sħiħa tagħha:

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}")

Agħmilha drawwa li ssejjaħ din l-operazzjoni qabel korsa kbira ta’ ġenerazzjoni. Dan jivverifika li l-voice_id imwaħħal fil-kodiċi (hardcoded) fl-applikazzjoni tiegħek jipponta lejn il-vuċi mistennija u mhux waħda minn proġett antik.

Tista’ timmodifika l-metadata ta’ vuċi eżistenti mingħajr ma tmiss il-kampjun tal-awdjo:

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}")

Il-qasam modifikabbli jinkludu name, languages, gender, age, tags, u description. Il-kampjun oriġinali tal-awdjo, madankollu, ma jistax jiġi mmodifikat. Jekk trid tbiddel l-awdjo, trid toħloq vuċi ġdida. Fil-prattika, vuċi rreġistrata ħażin ma tistax tiġi rranġata—trid tiġi sostitwita, u se jkollok bżonn tippropaga l-voice_id il-ġdid fl-applikazzjonijiet kollha tiegħek.

Tħassir u Rikupru tal-Kampjun

It-tħassir huwa permanenti u irreversibbli:

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

Wara t-tħassir, kull talba ta’ ġenerazzjoni li tuża dak il-voice_id se tfalli. Xenarju klassiku ta’ nightmare: żviluppatur inaddaf vuċijiet tat-test, iħassar bi żball wieħed li qed imexxi effettivament l-IVR tas-sostenn, u l-inċident jinfaqqa fil-għodu fuq l-ewwel sejħa li tidħol. Dejjem kun żgur li l-applikazzjonijiet tiegħek huma aġġornati qabel ma tħassar vuċi fil-produzzjoni.

Tista’ wkoll tniżżel l-awdjo oriġinali użat biex toħloq vuċi:

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

Din il-karatteristika tgħinek tarkivja l-kampjuni tiegħek jew tivverifika l-kwalità tal-awdjo tas-sors jekk vuċi tiddiżappuntak. Billi tisma’ l-oriġinal, spiss tiskopri li d-difett mis-mugħ waqt il-ġenerazzjoni kien diġà preżenti fir-reġistrazzjoni.

Organizzazzjoni tal-Katalogu tal-Vuċijiet Tiegħek

Ġestjoni nadifa tispiċċa ftit u tipprevjeni konfużjoni sinifikanti. Semmi l-vuċijiet tiegħek b’mod ċar b’prefiss tal-proġett, issegwi mudelli bħal podcast-narrator jew app-assistant-fr, minflok voice1 u test-final-2. Uża tags biex tikkategorizza skont il-każ ta’ użu, il-proġett jew il-klijent, u tagħmel il-listi faċli biex jiġu mmaniġġjati hekk kif jikbru. Iddokumenta l-voice_ids fil-konfigurazzjoni tal-applikazzjoni tiegħek, qatt f’file iżolat fuq workstation. U qatt ma tħassar vuċi tal-produzzjoni mingħajr ma l-ewwel tivverifika li m’għadhiex irreferenzjata mkien.

Punti Ewlenin

  • L-API tal-Vuċijiet tesponi kapaċitajiet CRUD sħaħ: oħloq, elenka, irrikupra, aġġorna, ħassar
  • Kull vuċi tirċievi voice_id uniku użat fit-talbiet ta’ ġenerazzjoni
  • Il-paġinazzjoni bbażata fuq l-offset tippermettilek timmaniġġja numru kbir ta’ vuċijiet
  • It-tħassir huwa permanenti—it-talbiet kollha li jużaw dik il-voice_id se jfallu
  • Il-kampjun oriġinali tal-awdjo jista’ jiġi rikuprat permezz tal-endpoint tal-kampjun