API de transcripció fora de línia
Na ovoj stranici
Curs actualitzat el 3 de novembre de 2026 per a Voxtral 3, basat en la guia Migrate from Voxtral 2 de Mistral: els models de Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603, obsolets des del 31 d’octubre de 2026 i retirats el 30 d’abril de 2027) se substitueixen als exemples pervoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3ivoxtral-mini-tts-3-0. Canvis clau: les marques temporals són només per segments (wordretorna un error 400), es compatibilitza la diarització en temps real, la configuració de sessió en temps real es bloqueja després del primer fragment d’àudio i les entrades decontext_biassón de format lliure (frases amb espais). Fonts: Migrate from Voxtral 2 · Speech to Text.
El punt final de transcripció
L’API de transcripció fora de línia de Mistral utilitza el punt final /audio/transcriptions. Es tracta d’una API síncrona: envies un fitxer d’àudio, la sol·licitud roman oberta durant el processament i reps la transcripció completa a la resposta. No hi ha cap ID de tasca per consultar ni cap webhook per configurar. Això simplifica notablement el teu codi, però has de permetre temps d’espera generosos per a fitxers llargs.
Abans de començar a programar, assegura’t de tenir tres requisits previs: un compte a la plataforma Mistral (console.mistral.ai), una clau API activa i l’SDK de Python instal·lat.
Instal·lació de l’SDK
pip install mistralai
Paràmetres de la crida
Tot passa a través de client.audio.transcriptions.complete(). Dos paràmetres són obligatoris i quatre són opcionals. Aquests paràmetres opcionals són els que converteixen una transcripció en brut en un lliurable utilitzable.
Paràmetres obligatoris
model— L’identificador del model. Per a la transcripció fora de línia, utilitza"voxtral-mini-transcribe-3"(recomanat) o una versió fixada com"voxtral-mini-transcribe-3".fileofile_url— El fitxer d’àudio a transcriure. Tens dues opcions:file: Un diccionari{"content": file_object, "file_name": "name.mp3"}per a la càrrega directa.file_url: Un URL públic que apunta al fitxer d’àudio.
Tria entre file i file_url és una decisió arquitectònica. Si el teu àudio ja està emmagatzemat en una ubicació accessible públicament, file_url evita encaminar el fitxer a través del teu servidor. Si el fitxer prové del dispositiu d’un usuari o d’un emmagatzematge privat, la càrrega directa és necessària.
Paràmetres opcionals
Quatre configuracions opcionals canvien la naturalesa de la sortida.
language espera un codi d’idioma ISO, com ara "fr" o "en", i evita la detecció automàtica. Força això per a lots homogenis, com un catàleg d’entrevistes realitzades íntegrament en francès, per evitar que un breu passatge en anglès canviï el model a mig fitxer. Tingues en compte que és incompatible amb timestamp_granularities.
timestamp_granularities accepta la llista ["segment"] i activa la devolució de marques temporals segment per segment. Amb Voxtral 3, la granularitat word ja no existeix i retorna un error 400. Aquest paràmetre permet fitxers de subtítols sincronitzats amb vídeo o passatges indexats en una conferència de dues hores.
diarize és un booleà. Quan s’estableix a True, el model identifica els parlants i atribueix cada segment a un d’ells. Per a un comitè executiu de sis persones, això marca la diferència entre un mur de text anònim i un informe on cada compromís és atribuïble.
Finalment, context_bias accepta una llista de termes: una sola paraula o una frase amb espais, com el nom d’un producte, per millorar el reconeixement d’un vocabulari específic. El nombre d’entrades ja no està fixat, però comparteixen la finestra de context amb l’àudio, així que mantingues la llista curta. Una reunió d’enginyeria amb termes com “Kubernetes” i “GDPR” esdevé significativament més llegible amb aquesta configuració.
Formats d’àudio compatibles
Voxtral accepta formats d’àudio comuns i rarament hauràs de convertir res prèviament. En cas de dubte, consulta la pàgina Audio formats de la documentació.
| Format | Característica |
|---|---|
| MP3 | El més comú, bona compressió |
| WAV | Sense compressió, màxima qualitat |
| FLAC | Compressió sense pèrdues |
| OGG | Format obert, bona compressió |
| M4A / AAC | Format Apple, comú en mòbils |
| WEBM | Format web, comú per a gravacions al navegador |
El límit crític és la finestra de context del model, que es comparteix entre l’àudio i el vocabulari de context_bias. Una sol·licitud que superi aquest límit es rebutja amb un error 400; l’API no trunca el fitxer. Per a fitxers molt llargs, com un seminari d’un dia sencer, divideix-los abans d’enviar-los, preferiblement en punts de silenci per evitar tallar frases per la meitat.
Estructura de la resposta
La resposta conté com a mínim el text transcrit:
response.text # El text transcrit complet (str)
Si has sol·licitat marques temporals (timestamp_granularities), la resposta també inclou:
response.segments # Llista de segments amb inici, final i text
Si has activat la diarització (diarize=True), cada segment inclou la identitat del parlant:
segment.speaker_id # Identificador del parlant (str)
segment.start # Temps d'inici en segons (float)
segment.end # Temps de finalització en segons (float)
segment.text # Text del segment (str)
En resum, la forma de l’objecte retornat depèn de la teva sol·licitud. El codi que iteri sobre response.segments sense passar timestamp_granularities fallarà. Verifica sempre la coherència entre els teus paràmetres d’entrada i el tractament de la sortida.
Combinacions de paràmetres
Aquestes són les cinc combinacions vàlides que trobaràs més sovint, de la més simple a la més especialitzada.
# Transcripció simple (només text)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Amb idioma forçat (sense marques temporals)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Amb marques temporals per segment
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Amb diarització + marques temporals
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Amb biaix de context
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Una restricció sorprenent a Voxtral 2 era que language i timestamp_granularities no es podien utilitzar junts en la mateixa crida. La documentació de Voxtral 3 ja no esmenta aquesta restricció; verifica-ho amb una prova abans de confiar-hi.
Autenticació
Totes les sol·licituds requereixen una clau API vàlida passada al constructor del client. En desenvolupament, n’hi ha prou amb un argument directe. En producció, utilitza una variable d’entorn per evitar que la clau acabi al teu repositori Git.
from mistralai.client import Mistral
# Via argument directe
client = Mistral(api_key="your-api-key")
# O via variable d'entorn (recomanat per a producció)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Ključne točke
- El punt final
/audio/transcriptionsés síncron: envia el fitxer, rep el text. - Dos modes de càrrega: càrrega directa (
file) o URL pública (file_url). - Paràmetres opcionals:
language,timestamp_granularities,diarize,context_bias. - A Voxtral 2,
languageitimestamp_granularitieseren mútuament excloents; la documentació de Voxtral 3 ja no ho indica. - S’admeten formats d’àudio comuns; el límit és la finestra de context compartida entre l’àudio i
context_bias(error 400 si se supera). - La diarització i les marques temporals es poden combinar.