API за гласове
На тази страница
Курсът е актуализиран на 3 ноември 2026 г. за Voxtral TTS 3, въз основа на ръководството Миграция от Voxtral 2 и страниците на 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 препоръчва повторно измерване на латентността след миграцията. Източници: Миграция от Voxtral 2 · Генериране на реч.
Крайна точка /v1/voices
API за гласове на Mistral е Вашата входна точка за управление на персонализирани гласове. То предоставя пълен набор от CRUD операции – Create (Създаване), Read (Четене), Update (Актуализиране), Delete (Изтриване), позволявайки Ви да създавате, изброявате, извличате, модифицирате и изтривате гласове. Ако сте работили със стандартен REST API преди, сте на позната територия: тук нищо не се занимава директно с аудио обработка; става въпрос единствено за управление на каталог от обекти.
Всеки глас, създаден чрез API, получава уникален идентификатор, voice_id, който ще използвате по-късно за генериране на реч. Имайте предвид следното: гласовете са постоянни. След като бъдат създадени, те остават достъпни във Вашия акаунт, докато не бъдат изрично изтрити. Не е необходимо да изпращате отново аудио пробата за всяко генериране, така че Вашите приложения трябва само да съхраняват низ в своята конфигурация.
Създаване на глас
Създаването става чрез POST заявка към крайната точка /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): посочвате броя елементи с 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. Използвайте тагове, за да категоризирате по случай на употреба, проект или клиент, правейки списъците управляеми, докато растат. Документирайте voice_id във конфигурацията на Вашето приложение, никога в изолиран файл на работна станция. И никога не изтривайте производствен глас, без първо да проверите, че вече не се използва никъде.
Ключови изводи
- API за гласове предоставя пълни CRUD възможности: създаване, изброяване, извличане, актуализиране, изтриване
- Всеки глас получава уникален
voice_id, използван в заявките за генериране - Страницитерането базирано на отместване Ви позволява да управлявате голям брой гласове
- Изтриването е окончателно – всички заявки, използващи този voice_id, ще се провалят
- Оригиналната аудио проба може да бъде извлечена чрез крайната точка за проби