API de texto a voz con Python para aplicaciones en tiempo real

Instala cartesia, define CARTESIA_API_KEY en el entorno del servidor y crea un cliente Cartesia. Llama a client.tts.generate con la transcripción, el modelo, el ID de voz y el formato de salida, y guarda la respuesta con write_to_file. El ejemplo de esta página produce speech.wav. Consulta los ejemplos de Python para ver solicitudes completas.

El SDK oficial requiere Python 3.9 o posterior. Instálalo con python -m pip install --upgrade cartesia. Para usar WebSocket, instala python -m pip install "cartesia[websockets]". Comprueba la versión instalada del paquete con la documentación del SDK al adaptar un ejemplo antiguo.

Sí. El endpoint de TTS admite salida WAV, MP3 y audio sin procesar. Elige el contenedor y sus parámetros compatibles en output_format antes de generar voz. Usa WAV para el ejemplo de esta página y MP3 cuando tu aplicación necesite ese formato. Cambiar solo la extensión del archivo no convierte el audio.

Usa WebSocket cuando tu aplicación reciba texto por partes. Envía esos fragmentos mediante un contexto de generación compartido y consume los fragmentos de audio devueltos a medida que lleguen. Tu aplicación sigue necesitando almacenar temporalmente y reproducir ese audio. La API WebSocket explica la continuación y la cancelación en aplicaciones conversacionales.

Usa HTTP cuando la transcripción ya esté disponible, por ejemplo, una narración completa o una notificación. Una respuesta HTTP también puede entregar audio progresivamente. Usa WebSocket cuando necesites enviar texto de forma incremental o gestionar una conversación continua. La entrada y la salida en streaming son decisiones independientes; guardar un archivo no es la única forma de consumir una respuesta HTTP.

Sí. Usa AsyncCartesia y espera sus llamadas a la API con await en una aplicación asíncrona. Los ejemplos asíncronos del SDK muestran generación, salida a archivos y streaming. Conecta el audio devuelto a la respuesta o al reproductor de tu aplicación y cierra el cliente cuando termine su ciclo de vida.

Mantén la clave de larga duración en una variable de entorno del servidor o en el gestor de secretos de la implementación. No la incluyas en commits ni la envíes al código del navegador. Si el navegador necesita una conexión directa, haz que el backend cree un token de corta duración y alcance limitado mediante la API de tokens de acceso.

Escucha una voz en Playground y envía su ID en la solicitud. Define language o locale para la transcripción, pero no ambos. Prueba nombres, números y abreviaturas de tus propios guiones. Consulta la referencia de solicitudes para ver los parámetros de idioma y voz, en lugar de asumir que todas las voces admiten los mismos acentos.

Elige un modelo de la documentación actual de Sonic y pruébalo con tu aplicación. El ID sonic-3.6 recibe actualizaciones de versiones estables. Una versión fechada publicada mantiene fijo el comportamiento del modelo mientras evalúas una nueva versión. Registra el ID del modelo junto con las pruebas para poder comparar resultados después de actualizar.

El audio PCM sin procesar no contiene una cabecera que indique cómo reproducirlo. El reproductor necesita la frecuencia de muestreo y la codificación usadas en la solicitud. Si no coinciden, puede producirse ruido, silencio o habla a una velocidad incorrecta. Empieza con salida WAV para comprobar la voz generada por separado del reproductor de streaming y después prueba la reproducción del audio sin procesar.

Gestiona los fallos de autenticación, los límites de solicitudes, los errores de red y los tiempos de espera. Configura los reintentos y los tiempos de espera del SDK según tu aplicación. Prueba las interrupciones de reproducción y evita reproducir audio en cola después de que el usuario cambie de dirección. Mide desde que el texto está disponible hasta que la voz se oye, incluidos la red y el búfer de reproducción.