Ga naar hoofdinhoud
Nederlands— Kies een taal
Menu

De offline transcriptie-API

Les 4 van 16 Bijgewerkt op 3 november 2026 Ontwikkelaar
Op deze pagina
  1. Het transcriptie-eindpunt
  2. Aanroepparameters
  3. Ondersteunde audioformaten
  4. Structuur van het antwoord
  5. Parametercombinaties
  6. Authenticatie
  7. Belangrijkste punten

Cursus bijgewerkt op 3 november 2026 voor Voxtral 3, gebaseerd op de gids Migrate from Voxtral 2 van Mistral: Voxtral 2-modellen (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), verouderd op 31 oktober 2026 en buiten gebruik gesteld op 30 april 2027, worden in de voorbeelden vervangen door voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 en voxtral-mini-tts-3-0. Belangrijkste wijzigingen: tijdstempels zijn alleen per segment (word geeft een 400-fout), real-time sprekerherkenning wordt ondersteund, sessie-instellingen voor real-time zijn vergrendeld na het eerste audioblok, en context_bias-items zijn vrij formaat (zinnen met spaties). Bronnen: Migrate from Voxtral 2 · Speech to Text.

Het transcriptie-eindpunt

De offline transcriptie-API van Mistral gebruikt het eindpunt /audio/transcriptions. Het is een synchrone API: u stuurt een audiobestand, het verzoek blijft open tijdens de verwerking en u ontvangt de volledige transcriptie in het antwoord. Er is geen taak-ID om te peilen en geen webhook om te configureren. Dit vereenvoudigt uw code aanzienlijk, maar u moet ruime time-outs toestaan voor lange bestanden.

Voordat u begint met coderen, zorgt u ervoor dat u drie vereisten heeft: een Mistral-platformaccount (console.mistral.ai), een actieve API-sleutel en de geïnstalleerde Python SDK.

De SDK installeren

pip install mistralai

Aanroepparameters

Alles verloopt via client.audio.transcriptions.complete(). Twee parameters zijn verplicht en vier zijn optioneel. Deze optionele parameters maken van een ruwe transcriptie een bruikbaar eindproduct.

Verplichte parameters

  • model — De modelidentificatie. Gebruik voor offline transcriptie "voxtral-mini-transcribe-3" (aanbevolen) of een gepinde versie zoals "voxtral-mini-transcribe-3".
  • file of file_url — Het audiobestand dat getranscribeerd moet worden. U heeft twee opties:
    • file: Een woordenboek {"content": file_object, "file_name": "name.mp3"} voor directe upload.
    • file_url: Een openbare URL die naar het audiobestand verwijst.

De keuze tussen file en file_url is een architecturale beslissing. Als uw audio al op een openbaar toegankelijke locatie staat, vermijdt file_url dat het bestand via uw server wordt gerouteerd. Als het bestand van het apparaat van een gebruiker of uit privéopslag komt, is directe upload noodzakelijk.

Optionele parameters

Vier optionele instellingen veranderen de aard van de uitvoer.

language verwacht een ISO-taalcode, zoals "fr" of "en", en slaat automatische detectie over. Forceer dit voor homogene batches, zoals een catalogus van interviews die volledig in het Frans zijn gevoerd, om te voorkomen dat een kort Engels fragment het model halverwege het bestand laat omschakelen. Let op: dit is niet compatibel met timestamp_granularities.

timestamp_granularities accepteert de lijst ["segment"] en activeert de retourwaarde van tijdstempels per segment. Bij Voxtral 3 bestaat de granulariteit word niet meer en geeft deze een 400-fout terug. Deze parameter maakt ondertitelbestanden mogelijk die gesynchroniseerd zijn met video of geïndexeerde fragmenten in een conferentie van twee uur.

diarize is een boolean. Wanneer ingesteld op True, identificeert het model sprekers en wijst elk segment aan een van hen toe. Voor een directiecomité van zes personen is dit het verschil tussen een anonieme muur van tekst en een rapport waarin elke toezegging herleidbaar is.

Ten slotte accepteert context_bias een lijst met termen—een enkel woord of een zin met spaties, zoals een productnaam—om de herkenning van specifieke vocabulaire te verbeteren. Het aantal items is niet langer vastgelegd, maar ze delen het contextvenster met de audio, dus houd de lijst kort. Een technische vergadering met termen als “Kubernetes” en “GDPR” wordt met deze instelling aanzienlijk leesbaarder.

Ondersteunde audioformaten

Voxtral accepteert gangbare audioformaten en u zult zelden iets vooraf hoeven converteren. Raadpleeg bij twijfel de pagina Audio formats in de documentatie.

FormaatKenmerk
MP3Meest gebruikelijk, goede compressie
WAVOngecomprimeerd, maximale kwaliteit
FLACLossless compressie
OGGOpen formaat, goede compressie
M4A / AACApple-formaat, veel gebruikt op mobiel
WEBMWebformaat, veel gebruikt voor browseropnames

De kritieke limiet is het contextvenster van het model, dat wordt gedeeld tussen de audio en het context_bias-vocabulaire. Een verzoek dat deze limiet overschrijdt, wordt geweigerd met een 400-fout; de API kapt het bestand niet af. Voor zeer lange bestanden, zoals een seminar van een hele dag, splitst u ze voordat u ze verzendt, bij voorkeur op stille punten om te voorkomen dat zinnen doormidden worden gesneden.

Structuur van het antwoord

Het antwoord bevat minimaal de getranscribeerde tekst:

response.text          # De volledige getranscribeerde tekst (str)

Als u tijdstempels heeft aangevraagd (timestamp_granularities), bevat het antwoord ook:

response.segments      # Lijst van segmenten met start, einde, tekst

Als u sprekerherkenning heeft ingeschakeld (diarize=True), bevat elk segment de identiteit van de spreker:

segment.speaker_id        # Identificatie van de spreker (str)
segment.start          # Starttijd in seconden (float)
segment.end            # Eindtijd in seconden (float)
segment.text           # Segmenttekst (str)

Kortom, de vorm van het geretourneerde object hangt af van uw verzoek. Code die iteratie over response.segments uitvoert zonder timestamp_granularities mee te geven, zal mislukken. Verifieer altijd de consistentie tussen uw invoerparameters en uw uitvoerverwerking.

Parametercombinaties

Hier zijn de vijf geldige combinaties die u het vaakst zult tegenkomen, van eenvoudig tot gespecialiseerd.

# Eenvoudige transcriptie (alleen tekst)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"}
)

# Met geforceerde taal (geen tijdstempels)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

# Met segment-tijdstempels
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    timestamp_granularities=["segment"]
)

# Met sprekerherkenning + tijdstempels
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    diarize=True,
    timestamp_granularities=["segment"]
)

# Met context-biasing
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/audio.mp3",
    context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)

Een verrassende beperking in Voxtral 2 was dat language en timestamp_granularities niet samen in dezelfde aanroep konden worden gebruikt. De documentatie van Voxtral 3 noemt deze beperking niet meer; verifieer dit met een test voordat u erop vertrouwt.

Authenticatie

Alle verzoeken vereisen een geldige API-sleutel die aan de client-constructor wordt doorgegeven. In ontwikkeling volstaat een direct argument. Gebruik in productie een omgevingsvariabele om te voorkomen dat de sleutel in uw Git-repository terechtkomt.

from mistralai.client import Mistral

# Via direct argument
client = Mistral(api_key="your-api-key")

# Of via omgevingsvariabele (aanbevolen voor productie)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Belangrijkste punten

  • Het eindpunt /audio/transcriptions is synchroon: verstuur het bestand, ontvang de tekst.
  • Twee uploadmodi: directe upload (file) of openbare URL (file_url).
  • Optionele parameters: language, timestamp_granularities, diarize, context_bias.
  • In Voxtral 2 waren language en timestamp_granularities wederzijds uitsluitend; de documentatie van Voxtral 3 stelt dit niet meer.
  • Gangbare audioformaten worden ondersteund; de limiet is het contextvenster dat wordt gedeeld tussen audio en context_bias (400-fout bij overschrijding).
  • Sprekerherkenning en tijdstempels kunnen worden gecombineerd.