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

La API de Voices

Lección 4 de 14 Actualizado el 3 de noviembre de 2026 Desarrollador
En esta página
  1. El punto de acceso /v1/voices
  2. Creación de una voz
  3. Listado, recuperación y modificación
  4. Eliminación y recuperación de la muestra
  5. Organización de tu catálogo de voces
  6. Puntos clave

Curso actualizado el 3 de noviembre de 2026 para Voxtral TTS 3, basado en la guía Migrate from Voxtral 2 y las páginas de Text to Speech de Mistral: voxtral-mini-tts-2603, obsoleto desde el 31 de octubre de 2026 y eliminado el 30 de abril de 2027, se sustituye en los ejemplos por voxtral-mini-tts-3-0. Las voces predefinidas de Voxtral 2 (gb_jane_neutral…) siguen siendo aceptadas; Voxtral 3 añade las etiquetas [emotion=…] y [pace=…] en el texto, el parámetro expressiveness, 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.

El punto de acceso /v1/voices

La API de Voices de Mistral es tu punto de entrada para gestionar voces personalizadas. Expone un conjunto completo de operaciones CRUD (Crear, Leer, Actualizar, Eliminar) que te permiten crear, listar, recuperar, modificar y borrar voces. Si has trabajado antes con una API REST estándar, estás en terreno conocido: nada de lo que hay aquí trata directamente con el procesamiento de audio; esto se limita exclusivamente a gestionar un catálogo de objetos.

Cada voz creada mediante la API recibe un identificador único, el voice_id, que utilizarás más adelante para generar voz. Ten presente esto: las voces son persistentes. Una vez creadas, permanecen disponibles en tu cuenta hasta que las elimines explícitamente. No necesitas reenviar la muestra de audio en cada generación, por lo que tus aplicaciones solo necesitan almacenar una cadena de texto en su configuración.

Creación de una voz

La creación se realiza mediante una llamada POST al punto de acceso /v1/voices. Debes proporcionar una muestra de audio codificada en base64 junto con metadatos descriptivos:

import base64
from pathlib import Path
from mistralai.client import Mistral

client = Mistral(api_key="your-api-key")

# Codificar la muestra de audio en base64
sample_audio_b64 = base64.b64encode(
    Path("sample.mp3").read_bytes()
).decode()

# Crear la voz
voice = client.audio.voices.create(
    name="my-pro-voice",
    sample_audio=sample_audio_b64,
    sample_filename="sample.mp3",
    languages=["fr", "en"],
    gender="female",
    age=35,
    tags=["professional", "podcast"]
)

print(f"Voz creada: {voice.id}")

El uso de base64 es necesario porque la solicitud es un documento JSON y JSON no puede transportar datos binarios. La API devuelve un objeto que contiene el voice_id que conservarás para todas las solicitudes de generación. En el ejemplo anterior lo imprimimos, pero en producción deberías escribirlo en tu configuración o base de datos.

Listado, recuperación y modificación

Para obtener una lista de todas tus voces, el método list() admite paginación:

# Obtener las primeras 10 voces
voices = client.audio.voices.list(limit=10, offset=0)

for v in voices.items:
    print(f"{v.id} — {v.name} ({v.gender}, {v.languages})")

La paginación se basa en desplazamiento (offset): especificas el número de elementos con limit y el punto de inicio con offset. Para explorar también las voces predefinidas de Mistral (Marie en francés, fr_marie_neutral, Jane en inglés británico, etc.), voices.search lista ambas familias, distinguidas por el campo type: preset o custom. Para obtener la segunda página de diez voces, llamas al método con offset=10. Este mecanismo resulta útil en cuanto una agencia gestiona voces para decenas de clientes.

Cuando necesitas detalles sobre una voz concreta, get() devuelve todos sus metadatos:

voice = client.audio.voices.get(voice_id="your-voice-id")

print(f"Nombre: {voice.name}")
print(f"Género: {voice.gender}")
print(f"Idiomas: {voice.languages}")
print(f"Etiquetas: {voice.tags}")

Acostúmbrate a llamar a esta operación antes de una ejecución de generación importante. Así verificas que el voice_id codificado en tu aplicación apunta a la voz esperada y no a una de un proyecto antiguo.

Puedes modificar los metadatos de una voz existente sin tocar la muestra de audio:

updated_voice = client.audio.voices.update(
    voice_id="your-voice-id",
    name="my-pro-voice-v2",
    languages=["fr", "en", "es"],
    tags=["professional", "podcast", "multilingual"]
)

print(f"Voz actualizada: {updated_voice.name}")

Los campos modificables incluyen name, languages, gender, age, tags y description. La muestra de audio original, sin embargo, no se puede modificar. Si quieres cambiar el audio, debes crear una nueva voz. En la práctica, una voz mal grabada no se puede reparar: hay que sustituirla y tendrás que propagar el nuevo voice_id por todas tus aplicaciones.

Eliminación y recuperación de la muestra

La eliminación es permanente e irreversible:

client.audio.voices.delete(voice_id="your-voice-id")
print("Voz eliminada")

Tras la eliminación, cualquier solicitud de generación que use ese voice_id fallará. Un escenario de pesadilla clásico: un desarrollador limpia voces de prueba, borra por error una que realmente está alimentando el IVR de soporte y el incidente estalla a la mañana siguiente con la primera llamada entrante. Asegúrate siempre de que tus aplicaciones están actualizadas antes de eliminar una voz en producción.

También puedes descargar el audio original utilizado para crear una voz:

response = client.audio.voices.get_sample_audio(voice_id="your-voice-id")
Path("retrieved_sample.mp3").write_bytes(response.content)

Esta función te ayuda a archivar tus muestras o a verificar la calidad del audio de origen si una voz te decepciona. Al escuchar el original, a menudo descubres que el defecto oído durante la generación ya estaba presente en la grabación.

Organización de tu catálogo de voces

Una gestión limpia cuesta poco y evita confusiones graves. Nombra tus voces con claridad usando un prefijo de proyecto, siguiendo patrones como podcast-narrator o app-assistant-fr, en lugar de voice1 y test-final-2. Usa etiquetas para categorizar por caso de uso, proyecto o cliente, de modo que las listas sean manejables a medida que crecen. Documenta los voice_id en la configuración de tu aplicación, nunca en un archivo aislado en una estación de trabajo. Y nunca elimines una voz de producción sin verificar antes que ya no se referencia en ningún sitio.

Puntos clave

  • La API de Voices expone capacidades CRUD completas: crear, listar, recuperar, actualizar, eliminar
  • Cada voz recibe un voice_id único utilizado en las solicitudes de generación
  • La paginación basada en desplazamiento permite gestionar un gran número de voces
  • La eliminación es permanente: todas las solicitudes que usen ese voice_id fallarán
  • La muestra de audio original se puede recuperar mediante el punto de acceso de muestras