Generación básica de voz
En esta página
Curso actualizado el 3 de noviembre de 2026 para Voxtral TTS 3, basándose en la guía Migrate from Voxtral 2 y en las páginas de Text to Speech de Mistral:
voxtral-mini-tts-2603, obsoleto desde el 31 de octubre de 2026 y retirado el 30 de abril de 2027, se sustituye en los ejemplos porvoxtral-mini-tts-3-0. Las voces predefinidas de Voxtral 2 (gb_jane_neutral…) siguen siendo válidas; Voxtral 3 añade las etiquetas[emotion=…]y[pace=…]en el texto, la configuraciónexpressiveness, la pronunciación personalizada (phoneme_hints) y 35 idiomas. Mistral recomienda volver a medir la latencia tras la migración. Fuentes: Migrate from Voxtral 2 · Speech generation.
Tu primera generación de voz
Ya sabes cómo crear una voz y gestionarla mediante la API de Voices. El paso final consiste en hacer aquello para lo que ha servido todo este trabajo: producir audio. La API de Speech de Mistral se reduce a una única llamada, client.audio.speech.complete(), que recibe texto y un ID de voz y devuelve audio codificado en base64. Esta lección cubre la generación básica con una voz guardada; la clonación al vuelo y la transmisión en streaming se verán a continuación.
El código siguiente es todo lo que necesitas para convertir una frase en un archivo MP3 en tu disco. Presta mucha atención al último paso: la respuesta no contiene bytes de audio brutos que puedas usar directamente, sino una cadena en base64 que debes decodificar antes de escribir el archivo. Este es el error clásico de principiante: guardar la cadena tal cual hace que los reproductores de audio se nieguen a abrirla.
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
# Generar voz con una voz guardada
response = client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="Hello and welcome to this course on Voxtral TTS.",
voice_id="your-voice-id",
response_format="mp3",
)
# Decodificar base64 y guardar en archivo
audio_bytes = base64.b64decode(response.audio_data)
Path("output.mp3").write_bytes(audio_bytes)
print(f"Audio generado: {len(audio_bytes)} bytes")
Qué controla cada parámetro
El parámetro model especifica el modelo de síntesis. A día de hoy, voxtral-mini-tts-3-0 es el único disponible, pero debes indicarlo siempre explícitamente: cuando aparezcan otros modelos, tu código seguirá produciendo exactamente la misma voz que produce hoy.
input recibe el texto que se va a hablar y es, con diferencia, el parámetro que requiere más atención. La documentación de Voxtral 2 aconsejaba no superar las 300 palabras por solicitud; la documentación de Voxtral TTS 3 ya no establece un límite, pero las solicitudes de un solo párrafo siguen siendo más fáciles de controlar y reproducir. Evita los emojis, que el modelo no puede interpretar, así como el formato complejo (Markdown, HTML, caracteres especiales), que acaba leyéndose literalmente. Por último, escribe los números y las abreviaturas con todas sus letras: «veintitrés» en lugar de «23», «Sociedad de Responsabilidad Limitada» en lugar de «S.L.». Un agente de voz que tropieza con los números al anunciar una cantidad pierde credibilidad en una sola frase.
voice_id identifica la voz utilizada. Puedes obtenerlo de tres formas: creando una voz con client.audio.voices.create() (véase la lección 5), listando tus voces existentes con client.audio.voices.list(), o reutilizando el ID de una voz profesional de Mistral. Por último, response_format establece el formato de salida entre mp3, wav, pcm, flac y opus. Esta elección afecta tanto al tamaño del archivo como a la latencia, y la lección 12 está dedicada íntegramente a ello.
Escalar: un capítulo de audiolibro
Para textos algo más largos, lo mejor es dividirlos. El principio es sencillo: prepara una lista de párrafos, genera cada uno por separado y acumula los bytes decodificados en un único búfer antes de escribir el archivo final.
import base64
from pathlib import Path
from mistralai.client import Mistral
client = Mistral(api_key="your-api-key")
voice_id = "your-voice-id"
# Texto dividido en párrafos
paragraphs = [
"First paragraph of the chapter. The narrator introduces the context.",
"Second paragraph. The action begins to develop.",
"Third paragraph. Suspense builds gradually.",
]
full_audio = b""
for i, text in enumerate(paragraphs):
print(f"Generating segment {i + 1}/{len(paragraphs)}...")
response = client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input=text,
voice_id=voice_id,
response_format="wav",
)
full_audio += base64.b64decode(response.audio_data)
Path("chapter-01.wav").write_bytes(full_audio)
print("Audio chapter generated successfully!")
Este script funciona porque produce WAV, un formato sin compresión cuyos segmentos pueden concatenarse extremo con extremo sin necesidad de un procesamiento especial. Si intentas hacer lo mismo con MP3 u Opus, el resultado será inutilizable: estos formatos comprimidos llevan cabeceras y estructuras de fotogramas que la concatenación en bruto rompe. En su lugar, utiliza una biblioteca como pydub, que decodifica cada segmento antes de fusionarlos limpiamente.
Cuándo falla la generación
En producción, debes proteger la llamada. Un voice_id eliminado ayer por un compañero, un texto que crece silenciosamente porque se ha concatenado un campo, una cuota de API agotada a fin de mes o un formato de salida mal escrito: cada una de estas situaciones lanza una excepción y, sin salvaguardas, tu procesamiento por lotes se detendrá a mitad del corpus.
try:
response = client.audio.speech.complete(
model="voxtral-mini-tts-3-0",
input="Text to convert to speech.",
voice_id=voice_id,
response_format="mp3",
)
audio_bytes = base64.b64decode(response.audio_data)
Path("output.mp3").write_bytes(audio_bytes)
except Exception as e:
print(f"Error during generation: {e}")
Tómate tu tiempo para probar esta ruta de error antes de pasar a producción: genera deliberadamente con un voice_id falso y verifica que tu aplicación lo señale claramente en lugar de producir un archivo vacío.
Puntos clave
- La generación usa
client.audio.speech.complete()con el modelovoxtral-mini-tts-3-0 - Divide los textos largos en párrafos y evita emojis y formato
- Escribe los números y las abreviaturas con todas sus letras para una pronunciación correcta
- El audio devuelto está en base64: decodifícalo antes de guardarlo
- Para textos largos, divídelos en segmentos y concatena los resultados