Премини към основното съдържание
Български— Изберете език
Меню

API за офлайн транскрипция

Урок 4 от 16 Обновен 3 ноември 2026 г. Програмист
На тази страница
  1. Крайна точка за транскрипция
  2. Параметри на извикването
  3. Поддържани аудио формати
  4. Структура на отговора
  5. Комбинации от параметри
  6. Удостоверяване
  7. Ключови изводи

Курсът е актуализиран на 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 при надвишаване).
  • Разграничаването на говорещи и временните марки могат да се комбинират.