Przejdź do głównej treści
Polski— Wybierz język
Menu

Interfejs API transkrypcji offline

Lekcja 4 z 16 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Punkt końcowy transkrypcji
  2. Parametry wywołania
  3. Obsługiwane formaty audio
  4. Struktura odpowiedzi
  5. Kombinacje parametrów
  6. Uwierzytelnianie
  7. Kluczowe wnioski

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 przez voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 oraz voxtral-mini-tts-3-0. Kluczowe zmiany: znaczniki czasu dotyczą wyłącznie segmentów (word zwraca błąd 400), obsługiwana jest diarizacja w czasie rzeczywistym, ustawienia sesji w czasie rzeczywistym są blokowane po pierwszym fragmencie audio, a wpisy context_bias mają 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".
  • file lub file_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.

FormatCharakterystyka
MP3Najpopularniejszy, dobra kompresja
WAVNieskompresowany, najwyższa jakość
FLACKompresja bezstratna
OGGFormat otwarty, dobra kompresja
M4A / AACFormat Apple, powszechny w urządzeniach mobilnych
WEBMFormat 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/transcriptions jest 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 language i timestamp_granularities wzajemnie 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ć.