Първото Ви обаждане за транскрипция
На тази страница
Курсът е актуализиран на 3 ноември 2026 г. за Voxtral 3, въз основа на ръководството на Mistral Migrate from Voxtral 2: Моделите Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603'), обявени за остарели на 31 октомври 2026 г. и премахнати на 30 април 2027 г., са заменени в примерите сvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3иvoxtral-mini-tts-3-0. Основни промени: временните марки са само за сегменти (wordвръща грешка 400), диаризацията е възможна в реално време, настройките на сесията в реално време се заключват след първия аудио чанк, а входовете заcontext_bias` са в свободен формат (фрази с интервали). Източници: Migrate from Voxtral 2 · Speech to Text.
Първата Ви транскрипция с Voxtral
Достатъчно теория. В този урок ще направите първото си пълно обаждане към API за офлайн транскрипция: локален аудиофайл се изпраща до Voxtral Mini Transcribe 3 и Вие обработвате върнатия текст. Кодът се събира в няколко реда, но след това ще го развием до надеждна версия, подходяща за автономна работа.
Подготовка на средата
SDK на Mistral се инсталира с една команда. Стъпката за проверка, която следва, Ви спестява търсенето на грешка при импортиране по-късно.
# Install the Mistral SDK
pip install mistralai
# Verify the installation
python -c "from mistralai.client import Mistral; print('SDK installed')"
Ще Ви е необходим API ключ на Mistral. Създайте такъв в console.mistral.ai и го съхранете в променлива на средата, вместо да го вграждате директно в кода:
export MISTRAL_API_KEY="your-api-key-here"
Транскрибиране на локален файл
Ето пълния код за транскрибиране на локален аудиофайл:
import os
from mistralai.client import Mistral
# Initialize the client
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Open and transcribe the audio file
with open("mon_audio.mp3", "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "mon_audio.mp3"}
)
# Display the result
print("=== Transcription ===")
print(response.text)
Това е. С четири реда активен код получавате пълната транскрипция на Вашия аудиофайл.
Нека разгледаме тези четири реда. Mistral(api_key=...) създава клиента с Вашия API ключ; това е обектът, който ще използвате повторно за всички последващи обаждания. open("mon_audio.mp3", "rb") отваря файла в двоичен режим, което е задължително за аудио – пропускането на b причинява грешка при декодиране, която е трудна за тълкуване. Параметърът file={"content": f, "file_name": "..."} очаква речник, съдържащ файловия обект и неговото име; това име не е просто декорация, то помага на сървъра да открие формата. Накрая, response.text съдържа пълната транскрипция като низ.
Транскрибиране от URL адрес
Ако Вашият аудиофайл вече е хостван онлайн, използвайте file_url вместо file:
import os
from mistralai.client import Mistral
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/mon_audio.mp3"
)
print(response.text)
URL адресът трябва да бъде публично достъпен. Сървърът на Mistral ще изтегли файла директно, което избягва маршрутизирането на аудиото през Вашата машина, когато то вече е в облака – значителна икономия на честотна лента за каталог от няколкостотин файла.
Преминаване към надеждна версия
Минималният скрипт работи за тест. В производствена среда трябва да обработвате липсващи файлове, неочаквани формати, липсващи ключове и мрежови грешки. Следващият скрипт извършва тези проверки преди обаждането и след това запазва резултата.
import os
import sys
from pathlib import Path
from mistralai.client import Mistral
def transcrire_audio(chemin_fichier: str) -> str:
"""Transcribes an audio file with Voxtral Mini Transcribe 3."""
# Check that the file exists
fichier = Path(chemin_fichier)
if not fichier.exists():
raise FileNotFoundError(f"Fichier introuvable : {chemin_fichier}")
# Check the extension
extensions_valides = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
if fichier.suffix.lower() not in extensions_valides:
raise ValueError(
f"Format non supporté : {fichier.suffix}. "
f"Formats valides : {', '.join(extensions_valides)}"
)
# Check size (practical limit: ~200 MB)
taille_mo = fichier.stat().st_size / (1024 * 1024)
if taille_mo > 200:
print(f"Attention : fichier volumineux ({taille_mo:.1f} Mo)")
# Initialize the client
api_key = os.environ.get("MISTRAL_API_KEY")
if not api_key:
raise EnvironmentError("Variable MISTRAL_API_KEY non définie")
client = Mistral(api_key=api_key)
# Transcribe
try:
with open(chemin_fichier, "rb") as f:
response = client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": fichier.name}
)
return response.text
except Exception as e:
raise RuntimeError(f"Erreur de transcription : {e}")
if __name__ == "__main__":
if len(sys.argv) < 2:
print("Usage : python transcrire.py <fichier_audio>")
sys.exit(1)
chemin = sys.argv[1]
print(f"Transcription de : {chemin}")
print("-" * 50)
texte = transcrire_audio(chemin)
print(texte)
# Save to text file
sortie = Path(chemin).stem + "_transcription.txt"
Path(sortie).write_text(texte, encoding="utf-8")
print(f"\nTranscription sauvegardée dans : {sortie}")
Стартирайте го от терминала, като предадете пътя до файла:
python transcribe.py meeting_march15.mp3
Скриптът проверява файла, транскрибира го, показва резултата и автоматично го запазва в .txt файл със същото основно име. Сега разполагате със скелет за пакетна обработка: обхождайте директория и Вашият аудиоархив се превръща в архив от текст, подлежащ на търсене.
Какво съдържа отговорът
Обектът response не се ограничава само до текст. Той предоставя и продължителността на обработеното аудио, както и езика, разпознат от модела – две полезни информации за регистриране на Вашите задачи и откриване на файлове, които не са на очаквания език.
# Full text
print(response.text)
# Audio duration (in seconds)
print(f"Durée : {response.duration:.1f}s")
# Detected language
print(f"Langue : {response.language}")
Най-добрият начин да оцените качеството на модела е да го тествате със собствения си глас. Запишете гласово съобщение с продължителност от тридесет секунди до две минути, стартирайте горния скрипт и сравнете резултата дума по дума с казаното от Вас: веднага ще видите къде са рядките грешки, почти винаги свързани със собствени имена. След това повторете упражнението с файл на друг език, без да променяте кода, за да наблюдавате автоматичното откриване на езика в действие.
Ключови изводи
- Минималното обаждане изисква 4 реда: клиент, отваряне на файл, API обаждане, четене на резултата
- Два режима на изпращане: локален файл (
file) или URL адрес (file_url) - Името на файла в речника
fileпомага за откриване на формата - В производствена среда добавете обработка на грешки (липсващ файл, невалиден формат, мрежова грешка)
response.textвинаги съдържа пълната транскрипция като низ