Ir al contenido principal
Español— Elegir un idioma
Menú

Tu primera llamada de transcripción

Lección 5 de 16 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. Tu primera transcripción con Voxtral
  2. Preparar el entorno
  3. Transcribir un archivo local
  4. Transcribir desde una URL
  5. Pasar a una versión robusta
  6. Qué contiene la respuesta
  7. Puntos clave

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 eliminados el 30 de abril de 2027, se sustituyen en los ejemplos por voxtral-mini-transcribe-3, voxtral-mini-transcribe-realtime-3yvoxtral-mini-tts-3-0. Cambios clave: las marcas de tiempo son solo por segmento (worddevuelve un error 400), la diarización es posible en tiempo real, la configuración de la sesión en tiempo real se bloquea tras el primer fragmento de audio y las entradas decontext_bias` son de formato libre (frases con espacios). Fuentes: Migrate from Voxtral 2 · Speech to Text.

Tu primera transcripción con Voxtral

Basta de teoría. En esta lección, realizarás tu primera llamada completa a la API de transcripción sin conexión: un archivo de audio local se envía a Voxtral Mini Transcribe 3 y procesas el texto devuelto. El código cabe en pocas líneas, pero luego lo evolucionaremos hasta una versión robusta apta para funcionamiento desatendido.

Preparar el entorno

El SDK de Mistral se instala con un solo comando. El paso de verificación siguiente te evita tener que buscar después un error de importación.

# Instalar el SDK de Mistral
pip install mistralai

# Verificar la instalación
python -c "from mistralai.client import Mistral; print('SDK instalado')"

Necesitarás una clave de API de Mistral. Crea una en console.mistral.ai y guárdala en una variable de entorno en lugar de codificarla directamente:

export MISTRAL_API_KEY="tu-clave-api-aqui"

Transcribir un archivo local

Este es el código completo para transcribir un archivo de audio local:

import os
from mistralai.client import Mistral

# Inicializar el cliente
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Abrir y transcribir el archivo de audio
with open("mon_audio.mp3", "rb") as f:
    response = client.audio.transcriptions.complete(
        model="voxtral-mini-transcribe-3",
        file={"content": f, "file_name": "mon_audio.mp3"}
    )

# Mostrar el resultado
print("=== Transcripción ===")
print(response.text)

Eso es todo. En cuatro líneas de código activo, obtienes la transcripción completa de tu archivo de audio.

Repasemos estas cuatro líneas. Mistral(api_key=...) crea el cliente con tu clave de API; este es el objeto que reutilizarás para todas las llamadas posteriores. open("mon_audio.mp3", "rb") abre el archivo en modo binario, algo obligatorio para audio; omitir la b provoca un error de decodificación difícil de interpretar. El parámetro file={"content": f, "file_name": "..."} espera un diccionario que contenga el objeto de archivo y su nombre; este nombre no es decorativo, ayuda al servidor a detectar el formato. Por último, response.text contiene la transcripción completa como una cadena de texto.

Transcribir desde una URL

Si tu archivo de audio ya está alojado en línea, usa file_url en lugar de file:

import os
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

response = client.audio.transcriptions.complete(
    model="voxtral-mini-transcribe-3",
    file_url="https://example.com/mon_audio.mp3"
)

print(response.text)

La URL debe ser accesible públicamente. El servidor de Mistral descargará el archivo directamente, lo que evita enrutar el audio a través de tu máquina cuando ya está en la nube; un ahorro significativo de ancho de banda para un catálogo de varios cientos de archivos.

Pasar a una versión robusta

El script mínimo funciona para una prueba. En producción, necesitas gestionar archivos faltantes, formatos inesperados, claves ausentes y errores de red. El siguiente script realiza estas comprobaciones antes de la llamada y luego guarda el resultado.

import os
import sys
from pathlib import Path
from mistralai.client import Mistral

def transcribir_audio(ruta_archivo: str) -> str:
    """Transcribe un archivo de audio con Voxtral Mini Transcribe 3."""

    # Comprobar que el archivo existe
    archivo = Path(ruta_archivo)
    if not archivo.exists():
        raise FileNotFoundError(f"Archivo no encontrado: {ruta_archivo}")

    # Comprobar la extensión
    extensiones_validas = {".mp3", ".wav", ".flac", ".ogg", ".m4a", ".webm"}
    if archivo.suffix.lower() not in extensiones_validas:
        raise ValueError(
            f"Formato no soportado: {archivo.suffix}. "
            f"Formatos válidos: {', '.join(extensiones_validas)}"
        )

    # Comprobar tamaño (límite práctico: ~200 MB)
    tamano_mb = archivo.stat().st_size / (1024 * 1024)
    if tamano_mb > 200:
        print(f"Atención: archivo voluminoso ({tamano_mb:.1f} MB)")

    # Inicializar el cliente
    api_key = os.environ.get("MISTRAL_API_KEY")
    if not api_key:
        raise EnvironmentError("Variable MISTRAL_API_KEY no definida")

    client = Mistral(api_key=api_key)

    # Transcribir
    try:
        with open(ruta_archivo, "rb") as f:
            response = client.audio.transcriptions.complete(
                model="voxtral-mini-transcribe-3",
                file={"content": f, "file_name": archivo.name}
            )
        return response.text
    except Exception as e:
        raise RuntimeError(f"Error de transcripción: {e}")

if __name__ == "__main__":
    if len(sys.argv) < 2:
        print("Uso: python transcribir.py <archivo_audio>")
        sys.exit(1)

    ruta = sys.argv[1]
    print(f"Transcripción de: {ruta}")
    print("-" * 50)

    texto = transcribir_audio(ruta)
    print(texto)

    # Guardar en archivo de texto
    salida = Path(ruta).stem + "_transcripcion.txt"
    Path(salida).write_text(texto, encoding="utf-8")
    print(f"\nTranscripción guardada en: {salida}")

Ejecútalo desde el terminal pasando la ruta del archivo:

python transcribir.py reunion_15marzo.mp3

El script comprueba el archivo, lo transcribe, muestra el resultado y lo guarda automáticamente en un archivo .txt con el mismo nombre base. Ya tienes el esqueleto para el procesamiento por lotes: recorre un directorio y tu archivo de audio se convierte en un archivo de texto consultable.

Qué contiene la respuesta

El objeto response no se limita al texto. También proporciona la duración del audio procesado y el idioma reconocido por el modelo; dos datos útiles para registrar tus trabajos y detectar archivos que no estén en el idioma esperado.

# Texto completo
print(response.text)

# Duración del audio (en segundos)
print(f"Duración: {response.duration:.1f}s")

# Idioma detectado
print(f"Idioma: {response.language}")

La mejor manera de evaluar la calidad del modelo es probarlo con tu propia voz. Graba un mensaje de voz de treinta segundos a dos minutos, ejecuta el script anterior y compara el resultado palabra por palabra con lo que dijiste: verás inmediatamente dónde se encuentran los raros errores, casi siempre en nombres propios. Luego repite el ejercicio con un archivo en otro idioma, sin cambiar el código, para observar la detección automática de idioma en acción.

Puntos clave

  • La llamada mínima requiere 4 líneas: cliente, apertura de archivo, llamada a la API, lectura del resultado
  • Dos modos de envío: archivo local (file) o URL (file_url)
  • El nombre del archivo en el diccionario file ayuda a la detección del formato
  • En producción, añade gestión de errores (archivo faltante, formato inválido, error de red)
  • response.text contiene siempre la transcripción completa como una cadena