Spring til hovedindhold
Dansk— Vælg et sprog
Menu

Offline Transcription API

Lektion 4 af 16 Opdateret 3. november 2026 Udvikler
På denne side
  1. Transskriptions-endpointet
  2. Kaldparametre
  3. Understøttede lydformater
  4. Responsstruktur
  5. Parameterkombinationer
  6. Godkendelse
  7. Vigtige pointer

Kurset opdateret den 3. november 2026 til Voxtral 3, baseret på Mistrals guide Migrate from Voxtral 2: Voxtral 2-modellerne (voxtral-mini-2602, voxtral-mini-transcribe-realtime-2602, voxtral-mini-tts-2603), der blev afskrevet den 31. oktober 2026 og udfases den 30. april 2027, erstattes i eksemplerne af voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3 og voxtral-mini-tts-3-0. Vigtige ændringer: Tidsstempler er kun tilgængelige på segmentniveau (word giver en 400-fejl), realtids-diarrisering understøttes, indstillinger for realtidssessioner låses efter det første lydstykke, og context_bias-poster er frit format (sætninger med mellemrum). Kilder: Migrate from Voxtral 2 · Speech to Text.

Transskriptions-endpointet

Mistrals offline transskriptions-API bruger endpointet /audio/transcriptions. Det er et synkront API: Du sender en lydfil, anmodningen holder forbindelsen åben under behandlingen, og du modtager hele transskriptionen i svaret. Der er intet task-ID, du skal spørge til, og ingen webhook, du skal konfigurere. Det forenkler din kode betydeligt, men du skal tillade generøse timeouts for lange filer.

Før du begynder at kode, skal du sikre dig tre forudsætninger: En Mistral platform-konto (console.mistral.ai), en aktiv API-nøgle og Python SDK installeret.

Installation af SDK

pip install mistralai

Kaldparametre

Alt foregår via client.audio.transcriptions.complete(). To parametre er obligatoriske, og fire er valgfrie. Det er disse valgfrie parametre, der omdanner en rå transskription til et brugbart leveranceprodukt.

Obligatoriske parametre

  • model — Modelidentifikatoren. Til offline transskription skal du bruge "voxtral-mini-transcribe-3" (anbefalet) eller en fastlåst version som "voxtral-mini-transcribe-3".
  • file eller file_url — Lydfilen, der skal transskriberes. Du har to muligheder:
    • file: En ordbog {"content": file_object, "file_name": "name.mp3"} til direkte upload.
    • file_url: En offentlig URL, der peger på lydfilen.

Valget mellem file og file_url er en arkitektonisk beslutning. Hvis din lyd allerede er gemt et offentligt tilgængeligt sted, undgår file_url at routere filen gennem din server. Hvis filen kommer fra en brugers enhed eller privat lager, er direkte upload nødvendigt.

Valgfrie parametre

Fire valgfrie indstillinger ændrer outputtets karakter.

language forventer en ISO-sprogkode, f.eks. "fr" eller "en", og omgår automatisk detektering. Gennemtving dette for homogene batches, såsom et katalog over interviews udelukkende på fransk, for at forhindre, at en kort engelsk passage får modellen til at skifte midt i filen. Bemærk, at det er inkompatibelt med timestamp_granularities.

timestamp_granularities tager listen ["segment"] og udløser returnering af tidsstempler segment for segment. Med Voxtral 3 eksisterer granulariteten word ikke længere og returnerer en 400-fejl. Denne parameter muliggør undertekstfiler synkroniseret til video eller indekserede passager i en to timers konference.

diarize er en boolean. Når den sættes til True, identificerer modellen talere og tilskriver hvert segment til en af dem. For en direktion på seks personer er dette forskellen mellem en anonym væg af tekst og en rapport, hvor hver forpligtelse kan tilskrives.

Endelig accepterer context_bias en liste over termer – et enkelt ord eller en sætning med mellemrum, såsom et produktnavn – for at forbedre genkendelsen af specifikt ordforråd. Antallet af poster er ikke længere fastlåst, men de deler kontekstvinduet med lyden, så hold listen kort. Et ingeniørmøde med termer som “Kubernetes” og “GDPR” bliver væsentligt mere læseligt med denne indstilling.

Understøttede lydformater

Voxtral accepterer almindelige lydformater, og du vil sjældent skulle konvertere noget på forhånd. Hvis du er i tvivl, så henvis til siden Audio formats i dokumentationen.

FormatKarakteristik
MP3Mest almindelige, god komprimering
WAVUkomprimeret, maksimal kvalitet
FLACTabsfri komprimering
OGGÅbent format, god komprimering
M4A / AACApple-format, almindeligt på mobil
WEBMWeb-format, almindeligt til browseroptagelser

Den kritiske grænse er modellens kontekstvindue, som deles mellem lyden og context_bias-ordforrådet. En anmodning, der overskrider denne grænse, afvises med en 400-fejl; API’et afkorter ikke filen. For meget lange filer, såsom et endagsseminar, skal du opdele dem før afsendelse, helst ved stille punkter for at undgå at klippe sætninger over.

Responsstruktur

Svaret indeholder som minimum den transskriberede tekst:

response.text          # Den fulde transskriberede tekst (str)

Hvis du har anmodet om tidsstempler (timestamp_granularities), indeholder svaret også:

response.segments      # Liste over segmenter med start, slut, tekst

Hvis du har aktiveret diarrisering (diarize=True), inkluderer hvert segment talerens identitet:

segment.speaker_id        # Taleridentifikator (str)
segment.start          # Starttid i sekunder (float)
segment.end            # Sluttid i sekunder (float)
segment.text           # Segmenttekst (str)

Kort sagt afhænger formen på det returnerede objekt af din anmodning. Kode, der itererer over response.segments uden at sende timestamp_granularities, vil fejle. Verificér altid konsistensen mellem dine inputparametre og din output-håndtering.

Parameterkombinationer

Her er de fem gyldige kombinationer, du oftest vil støde på, fra den enkleste til den mest specialiserede.

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

# Med tvunget sprog (ingen tidsstempler)
client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file={"content": f, "file_name": "audio.mp3"},
    language="fr"
)

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

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

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

En overraskende begrænsning i Voxtral 2 var, at language og timestamp_granularities ikke kunne bruges sammen i samme kald. Voxtral 3-dokumentationen nævner ikke længere denne begrænsning; verificér dette med en test, før du stole på det.

Godkendelse

Alle anmodninger kræver en gyldig API-nøgle, der sendes til klient-konstruktøren. I udviklingsmiljøet er et direkte argument tilstrækkeligt. I produktion skal du bruge en miljøvariabel for at forhindre, at nøglen ender i dit Git-repository.

from mistralai.client import Mistral

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

# Eller via miljøvariabel (anbefalet til produktion)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

Vigtige pointer

  • Endpointet /audio/transcriptions er synkront: Send filen, modtag teksten.
  • To upload-tilstande: Direkte upload (file) eller offentlig URL (file_url).
  • Valgfrie parametre: language, timestamp_granularities, diarize, context_bias.
  • I Voxtral 2 var language og timestamp_granularities gensidigt udelukkende; Voxtral 3-dokumentationen angiver ikke længere dette.
  • Almindelige lydformater understøttes; grænsen er kontekstvinduet, der deles mellem lyd og context_bias (400-fejl hvis overskredet).
  • Diarrisering og tidsstempler kan kombineres.