API за офлайн транскрипция
На тази страница
Курсът е актуализиран на 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.
Крайна точка за транскрипция
Офлайн API за транскрипция на Mistral използва крайната точка /audio/transcriptions. Това е синхронно API: изпращате аудио файл, заявката остава отворена по време на обработката и получавате пълната транскрипция в отговора. Няма идентификатор на задача за периодична проверка (polling) и няма уебхук за конфигуриране. Това значително опростява кода Ви, но трябва да предвидите достатъчно дълги таймаути за дълги файлове.
Преди да започнете да пишете код, уверете се, че разполагате с три предпоставки: акаунт в платформата на Mistral (console.mistral.ai), активен API ключ и инсталиран Python SDK.
Инсталиране на SDK
pip install mistralai
Параметри на извикването
Всичко преминава през client.audio.transcriptions.complete(). Два параметъра са задължителни, а четири са незадължителни. Тези незадължителни параметри са това, което превръща суровата транскрипция в използваем резултат.
Задължителни параметри
model— Идентификаторът на модела. За офлайн транскрипция използвайте"voxtral-mini-transcribe-3"(препоръчително) или фиксирана версия като"voxtral-mini-transcribe-3".fileилиfile_url— Аудио файлът за транскрибиране. Имате две опции:file: Речник{"content": file_object, "file_name": "name.mp3"}за директно качване.file_url: Публичен URL адрес, сочещ към аудио файла.
Изборът между file и file_url е архитектурно решение. Ако аудиото Ви вече се съхранява на публично достъпно място, file_url избягва маршрутизирането на файла през Вашия сървър. Ако файлът идва от устройството на потребителя или от частно хранилище, е необходимо директно качване.
Незадължителни параметри
Четири незадължителни настройки променят естеството на изхода.
language очаква ISO код на езика, като "fr" или "en", и заобикаля автоматичното откриване. Принудително задавайте това за хомогенни пакети, като например каталог с интервюта, проведени изцяло на френски, за да предотвратите преминаването на модела към друг език при кратък английски pasaj във файла. Имайте предвид, че е несъвместим с timestamp_granularities.
timestamp_granularities приема списъка ["segment"] и задейства връщането на временни марки сегмент по сегмент. С Voxtral 3 гранулярността word вече не съществува и връща грешка 400. Този параметър позволява създаването на файлове със субтитри, синхронизирани с видео, или индексирани пасажи в двучасова конференция.
diarize е булева стойност. Когато е зададена на True, моделът идентифицира говорещите и приписва всеки сегмент на един от тях. За изпълнителен комитет от шест души това е разликата между анонимна стена от текст и доклад, в който всяко поето ангажимент може да бъде атрибутиран.
Накрая, context_bias приема списък от термини – отделна дума или фраза с интервали, като име на продукт – за подобряване на разпознаването на специфичен речник. Броят на записите вече не е фиксиран, но те споделят контекстния прозорец с аудиото, затова поддържайте списъка кратък. Инженерна среща, включваща термини като “Kubernetes” и “GDPR”, става значително по-четима с тази настройка.
Поддържани аудио формати
Voxtral приема обичайните аудио формати и рядко ще се наложи да конвертирате каквото и да е предварително. Ако се съмнявате, вижте страницата Audio formats в документацията.
| Формат | Характеристика |
|---|---|
| MP3 | Най-често срещан, добра компресия |
| WAV | Некомпресиран, максимално качество |
| FLAC | Компресия без загуба на качество |
| OGG | Отворен формат, добра компресия |
| M4A / AAC | Формат на Apple, често срещан при мобилни устройства |
| WEBM | Уеб формат, често срещан при записи в браузър |
Критичното ограничение е контекстният прозорец на модела, който се споделя между аудиото и речника context_bias. Заявка, надвишаваща този лимит, се отхвърля с грешка 400; API не съкращава файла. За много дълги файлове, като например целодневен семинар, ги разделете преди изпращане, за предпочитане на места с тишина, за да избегнете прекъсване на изреченията по средата.
Структура на отговора
Отговорът съдържа поне транскрибирания текст:
response.text # Пълният транскрибиран текст (str)
Ако сте поискали временни марки (timestamp_granularities), отговорът включва също:
response.segments # Списък със сегменти с начало, край и текст
Ако сте активирали разграничаване на говорещи (diarize=True), всеки сегмент включва идентичността на говорещия:
segment.speaker_id # Идентификатор на говорещия (str)
segment.start # Време на начало в секунди (float)
segment.end # Време на край в секунди (float)
segment.text # Текст на сегмента (str)
Накратко, формата на върнатия обект зависи от Вашата заявка. Код, който итерира през response.segments, без да предаде timestamp_granularities, ще се провали. Винаги проверявайте съгласуваността между входните си параметри и обработката на изхода.
Комбинации от параметри
Ето петте валидни комбинации, които ще срещнете най-често, от най-простата до най-специализираната.
# Обикновена транскрипция (само текст)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# С принудителен език (без временни марки)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# С временни марки за сегменти
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# С разграничаване на говорещи + временни марки
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# С контекстно пристрастяване (context biasing)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Изненадващо ограничение във Voxtral 2 беше, че language и timestamp_granularities не можеха да се използват заедно в едно и също извикване. Документацията на Voxtral 3 вече не споменава това ограничение; проверете това с тест, преди да разчитате на него.
Удостоверяване
Всички заявки изискват валиден API ключ, предаден на конструктора на клиента. По време на разработка е достатъчен директен аргумент. В производствена среда използвайте променлива на средата, за да предотвратите попадането на ключа във Вашето Git хранилище.
from mistralai.client import Mistral
# Чрез директен аргумент
client = Mistral(api_key="your-api-key")
# Или чрез променлива на средата (препоръчително за производство)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Ключови изводи
- Крайната точка
/audio/transcriptionsе синхронна: изпратете файла, получете текста. - Два режима на качване: директно качване (
file) или публичен URL адрес (file_url). - Незадължителни параметри:
language,timestamp_granularities,diarize,context_bias. - Във Voxtral 2
languageиtimestamp_granularitiesбяха взаимно изключващи се; документацията на Voxtral 3 вече не посочва това. - Поддържат се обичайни аудио формати; ограничението е контекстният прозорец, споделен между аудиото и
context_bias(грешка 400 при надвишаване). - Разграничаването на говорещи и временните марки могат да се комбинират.