La API de transcripción sin conexión
En esta página
Curso actualizado el 3 de noviembre de 2026 para Voxtral 3, basado en la guía Migrate from Voxtral 2 de Mistral: los modelos de Voxtral 2 (
voxtral-mini-2602,voxtral-mini-transcribe-realtime-2602,voxtral-mini-tts-2603), obsoletos desde el 31 de octubre de 2026 y retirados el 30 de abril de 2027, se sustituyen en los ejemplos porvoxtral-mini-transcribe-3,voxtral-mini-transcribe-realtime-3yvoxtral-mini-tts-3-0. Cambios clave: las marcas temporales son solo por segmentos (worddevuelve un error 400), se admite la diarización en tiempo real, la configuración de sesión en tiempo real se bloquea tras el primer fragmento de audio y las entradas decontext_biasson de formato libre (frases con espacios). Fuentes: Migrate from Voxtral 2 · Speech to Text.
El extremo de transcripción
La API de transcripción sin conexión de Mistral utiliza el extremo /audio/transcriptions. Se trata de una API síncrona: envías un archivo de audio, la solicitud permanece abierta durante el procesamiento y recibes la transcripción completa en la respuesta. No hay ningún ID de tarea que sondear ni ningún webhook que configurar. Esto simplifica considerablemente tu código, pero debes permitir tiempos de espera generosos para archivos largos.
Antes de empezar a programar, asegúrate de cumplir tres requisitos previos: una cuenta en la plataforma Mistral (console.mistral.ai), una clave de API activa y el SDK de Python instalado.
Instalación del SDK
pip install mistralai
Parámetros de la llamada
Todo se gestiona a través de client.audio.transcriptions.complete(). Dos parámetros son obligatorios y cuatro opcionales. Estos parámetros opcionales son los que convierten una transcripción en bruto en un entregable utilizable.
Parámetros obligatorios
model— El identificador del modelo. Para la transcripción sin conexión, utiliza"voxtral-mini-transcribe-3"(recomendado) o una versión fija como"voxtral-mini-transcribe-3".fileofile_url— El archivo de audio que deseas transcribir. Tienes dos opciones:file: Un diccionario{"content": file_object, "file_name": "name.mp3"}para la carga directa.file_url: Una URL pública que apunte al archivo de audio.
Elegir entre file y file_url es una decisión arquitectónica. Si tu audio ya está almacenado en una ubicación accesible públicamente, file_url evita enrutar el archivo a través de tu servidor. Si el archivo proviene del dispositivo de un usuario o de un almacenamiento privado, es necesaria la carga directa.
Parámetros opcionales
Cuatro ajustes opcionales modifican la naturaleza del resultado.
language espera un código de idioma ISO, como "fr" o "en", y omite la detección automática. Fuerza este parámetro para lotes homogéneos, como un catálogo de entrevistas realizadas íntegramente en francés, para evitar que un breve pasaje en inglés haga cambiar al modelo a mitad del archivo. Ten en cuenta que es incompatible con timestamp_granularities.
timestamp_granularities acepta la lista ["segment"] y activa la devolución de marcas temporales segmento a segmento. Con Voxtral 3, la granularidad word ya no existe y devuelve un error 400. Este parámetro permite generar archivos de subtítulos sincronizados con vídeo o pasajes indexados en una conferencia de dos horas.
diarize es un booleano. Cuando se establece en True, el modelo identifica a los interlocutores y atribuye cada segmento a uno de ellos. Para un comité ejecutivo de seis personas, esto marca la diferencia entre un muro de texto anónimo y un informe donde cada compromiso es atribuible.
Por último, context_bias acepta una lista de términos, ya sea una sola palabra o una frase con espacios, como el nombre de un producto, para mejorar el reconocimiento de vocabulario específico. El número de entradas ya no está fijado, pero comparten la ventana de contexto con el audio, así que mantén la lista breve. Una reunión de ingeniería con términos como “Kubernetes” y “GDPR” se vuelve significativamente más legible con este ajuste.
Formatos de audio compatibles
Voxtral acepta formatos de audio comunes y raramente necesitarás convertir nada de antemano. En caso de duda, consulta la página Audio formats de la documentación.
| Formato | Característica |
|---|---|
| MP3 | El más común, buena compresión |
| WAV | Sin compresión, calidad máxima |
| FLAC | Compresión sin pérdida |
| OGG | Formato abierto, buena compresión |
| M4A / AAC | Formato Apple, común en móviles |
| WEBM | Formato web, común en grabaciones de navegador |
El límite crítico es la ventana de contexto del modelo, que se comparte entre el audio y el vocabulario de context_bias. Una solicitud que exceda este límite se rechazará con un error 400; la API no trunca el archivo. Para archivos muy largos, como un seminario de todo un día, divídelos antes de enviarlos, preferiblemente en puntos de silencio para evitar cortar frases por la mitad.
Estructura de la respuesta
La respuesta contiene como mínimo el texto transcrito:
response.text # El texto transcrito completo (str)
Si has solicitado marcas temporales (timestamp_granularities), la respuesta también incluye:
response.segments # Lista de segmentos con inicio, fin y texto
Si has activado la diarización (diarize=True), cada segmento incluye la identidad del interlocutor:
segment.speaker_id # Identificador del interlocutor (str)
segment.start # Tiempo de inicio en segundos (float)
segment.end # Tiempo de fin en segundos (float)
segment.text # Texto del segmento (str)
En resumen, la forma del objeto devuelto depende de tu solicitud. El código que iteré sobre response.segments sin pasar timestamp_granularities fallará. Verifica siempre la coherencia entre tus parámetros de entrada y tu gestión de la salida.
Combinaciones de parámetros
Estas son las cinco combinaciones válidas que encontrarás con más frecuencia, de la más sencilla a la más especializada.
# Transcripción simple (solo texto)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"}
)
# Con idioma forzado (sin marcas temporales)
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
language="fr"
)
# Con marcas temporales por segmento
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
timestamp_granularities=["segment"]
)
# Con diarización + marcas temporales
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file={"content": f, "file_name": "audio.mp3"},
diarize=True,
timestamp_granularities=["segment"]
)
# Con sesgo de contexto
client.audio.transcriptions.complete(
model="voxtral-mini-transcribe-3",
file_url="https://example.com/audio.mp3",
context_bias=["Mistral", "Voxtral", "Corsen", "GDPR"]
)
Una restricción sorprendente en Voxtral 2 era que language y timestamp_granularities no podían usarse juntos en la misma llamada. La documentación de Voxtral 3 ya no menciona esta restricción; verifícalo con una prueba antes de depender de ello.
Autenticación
Todas las solicitudes requieren una clave de API válida pasada al constructor del cliente. En desarrollo, basta con un argumento directo. En producción, utiliza una variable de entorno para evitar que la clave acabe en tu repositorio de Git.
from mistralai.client import Mistral
# Mediante argumento directo
client = Mistral(api_key="your-api-key")
# O mediante variable de entorno (recomendado para producción)
import os
os.environ["MISTRAL_API_KEY"] = "your-api-key"
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
Puntos clave
- El extremo
/audio/transcriptionses síncrono: envías el archivo y recibes el texto. - Dos modos de carga: carga directa (
file) o URL pública (file_url). - Parámetros opcionales:
language,timestamp_granularities,diarize,context_bias. - En Voxtral 2,
languageytimestamp_granularitieseran mutuamente excluyentes; la documentación de Voxtral 3 ya no indica esto. - Se admiten formatos de audio comunes; el límite es la ventana de contexto compartida entre el audio y
context_bias(error 400 si se excede). - La diarización y las marcas temporales pueden combinarse.