Interfejs API transkrypcji offline
Na tej stronie
Kurs zaktualizowany 3 listopada 2026 r. dla Voxtral 3, na podstawie przewodnika Mistral Migrate from Voxtral 2: modele Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), wycofane 31 października 2026 r. i całkowicie usunięte 30 kwietnia 2027 r., zostały zastąpione w przykładach przezvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3orazvoxtral-mini-tts-3-0. Kluczowe zmiany: znaczniki czasu dotyczą wyłącznie segmentów (wordzwraca błąd 400), obsługiwana jest diarizacja w czasie rzeczywistym, ustawienia sesji w czasie rzeczywistym są blokowane po pierwszym fragmencie audio, a wpisycontext_biasmają dowolną formę (frazy ze spacjami). Źródła: Migrate from Voxtral 2 · Speech to Text.
Punkt końcowy transkrypcji
Interfejs API transkrypcji offline od Mistral korzysta z punktu końcowego /audio/transcriptions. Jest to API synchroniczne: wysyłasz plik audio, żądanie pozostaje otwarte podczas przetwarzania, a w odpowiedzi otrzymujesz pełną transkrypcję. Nie ma identyfikatora zadania do odpytywania ani webhooka do konfiguracji. Znacznie upraszcza to Twój kod, ale musisz przewidzieć odpowiednie limity czasu oczekiwania dla długich plików.
Zanim zaczniesz programować, upewnij się, że masz trzy rzeczy: konto na platformie Mistral (console.mistral.ai), aktywny klucz API oraz zainstalowany SDK dla Pythona.
Instalacja SDK
pip install mistralai
Parametry wywołania
Wszystko odbywa się poprzez client.audio.transcriptions.complete(). Dwa parametry są wymagane, a cztery opcjonalne. To właśnie te opcjonalne parametry zamieniają surową transkrypcję w użyteczny produkt.
Parametry wymagane
model— Identyfikator modelu. Do transkrypcji offline użyj"voxtral-mini-transcribe-3"(zalecane) lub konkretnej wersji, np."voxtral-mini-transcribe-3".filelubfile_url— Plik audio do transkrypcji. Masz dwie opcje:file: Słownik{"content": file_object, "file_name": "name.mp3"}do bezpośredniego przesłania.file_url: Publiczny URL wskazujący na plik audio.
Wybór między file a file_url to decyzja architektoniczna. Jeśli Twoje audio jest już przechowywane w publicznie dostępnym miejscu, file_url pozwala uniknąć przesyłania pliku przez Twój serwer. Jeśli plik pochodzi z urządzenia użytkownika lub prywatnego magazynu, konieczne jest bezpośrednie przesłanie.
Parametry opcjonalne
Cztery opcjonalne ustawienia zmieniają charakter wyniku.
language oczekuje kodu języka ISO, takiego jak "fr" lub "en", i pomija automatyczne wykrywanie. Wymuś to dla jednorodnych partii danych, np. katalogu wywiadów przeprowadzonych wyłącznie po francusku, aby krótki fragment po angielsku nie spowodował przełączenia modelu w trakcie przetwarzania pliku. Pamiętaj, że jest to niekompatybilne z timestamp_granularities.
timestamp_granularities przyjmuje listę ["segment"] i wyzwala zwracanie znaczników czasu segment po segmencie. W Voxtral 3 granularność word już nie istnieje i zwraca błąd 400. Parametr ten umożliwia tworzenie plików z napisami synchronizowanymi z wideo lub indeksowanie fragmentów w dwugodzinnej konferencji.
diarize to wartość logiczna (boolean). Gdy ustawiona na True, model identyfikuje mówców i przypisuje każdy segment do jednego z nich. W przypadku sześcioosobowego komitetu wykonawczego jest to różnica między anonimową ścianą tekstu a raportem, w którym każde zobowiązanie można przypisać konkretnej osobie.
Na koniec, context_bias przyjmuje listę terminów – pojedyncze słowo lub frazę ze spacjami, np. nazwę produktu – aby poprawić rozpoznawanie specyficznego słownictwa. Liczba wpisów nie jest już stała, ale dzielą one okno kontekstowe z audio, więc utrzymuj listę krótką. Spotkanie inżynierskie z terminami takimi jak „Kubernetes“ i „RODO“ staje się dzięki temu ustawieniu znacznie czytelniejsze.
Obsługiwane formaty audio
Voxtral akceptuje popularne formaty audio i rzadko będziesz musiał coś wcześniej konwertować. W razie wątpliwości sprawdź stronę Audio formats w dokumentacji.
| Format | Charakterystyka |
|---|---|
| MP3 | Najpopularniejszy, dobra kompresja |
| WAV | Nieskompresowany, najwyższa jakość |
| FLAC | Kompresja bezstratna |
| OGG | Format otwarty, dobra kompresja |
| M4A / AAC | Format Apple, powszechny w urządzeniach mobilnych |
| WEBM | Format webowy, powszechny w nagraniach z przeglądarki |
Krytycznym limitem jest okno kontekstowe modelu, które jest współdzielone między audio a słownictwem context_bias. Żądanie przekraczające ten limit zostanie odrzucone z błędem 400; API nie przycina pliku. W przypadku bardzo długich plików, np. całodziennego seminarium, podziel je przed wysłaniem, najlepiej w miejscach ciszy, aby uniknąć przecinania zdań w połowie.
Struktura odpowiedzi
Odpowiedź zawiera co najmniej przetłumaczony tekst:
response.text # Pełny przetłumaczony tekst (str)
Jeśli zażądałeś znaczników czasu (timestamp_granularities), odpowiedź zawiera również:
response.segments # Lista segmentów z początkiem, końcem i tekstem
Jeśli włączyłeś diarizację (diarize=True), każdy segment zawiera tożsamość mówcy:
segment.speaker_id # Identyfikator mówcy (str)
segment.start # Czas rozpoczęcia w sekundach (float)
segment.end # Czas zakończenia w sekundach (float)
segment.text # Tekst segmentu (str)
Krótko mówiąc, kształt zwracanego obiektu zależy od Twojego żądania. Kod iterujący po response.segments bez przekazania timestamp_granularities zakończy się niepowodzeniem. Zawsze weryfikuj spójność między parametrami wejściowymi a obsługą wyjścia.
Kombinacje parametrów
Oto pięć poprawnych kombinacji, z którymi spotkasz się najczęściej, od najprostszych do najbardziej wyspecjalizowanych.
# Prosta transkrypcja (tylko tekst)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Z wymuszonym językiem (bez znaczników czasu)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Ze znacznikami czasu segmentów
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Z diarizacją + znacznikami czasu
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Z biasowaniem kontekstu
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Zaskakującym ograniczeniem w Voxtral 2 było to, że language i timestamp_granularities nie mogły być użyte razem w tym samym wywołaniu. Dokumentacja Voxtral 3 nie wspomina już o tym ograniczeniu; zweryfikuj to testem przed poleganiem na tej funkcji.
Uwierzytelnianie
Wszystkie żądania wymagają ważnego klucza API przekazanego do konstruktora klienta. W środowisku deweloperskim wystarczy bezpośredni argument. W produkcji użyj zmiennej środowiskowej, aby klucz nie trafił do Twojego repozytorium Git.
from mistralai.client import Mistral
# Poprzez bezpośredni argument
client = Mistral(api_key="your-api-key")
# Lub poprzez zmienną środowiskową (zalecane w produkcji)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Kluczowe wnioski
- Punkt końcowy
/audio/transcriptionsjest synchroniczny: wyślij plik, odbierz tekst. - Dwa tryby przesyłania: bezpośrednie przesłanie (
file) lub publiczny URL (file_url). - Parametry opcjonalne:
language,timestamp_granularities,diarize,context_bias. - W Voxtral 2
languageitimestamp_granularitieswzajemnie się wykluczały; dokumentacja Voxtral 3 już tego nie stwierdza. - Obsługiwane są popularne formaty audio; limitem jest okno kontekstowe współdzielone między audio a
context_bias(błąd 400 po przekroczeniu). - Diarizację i znaczniki czasu można łączyć.