Texto a voz con Python: guarda el audio en un archivo WAV

Para convertir texto a voz en Python, envía un texto a un modelo de voz y guarda el audio recibido. Esta guía usa el SDK de Python de Cartesia para generar un archivo WAV con Sonic.

Necesitas Python 3.9 o posterior, conexión a internet y una cuenta de Cartesia con acceso a la API. El ejemplo siguiente usa la versión 4.2.0 del SDK.¹ Llama a una API alojada, por lo que el texto sale de tu equipo. Si necesitas síntesis sin conexión, usa un motor de voz local.

Instala el SDK de Python

Crea un entorno virtual en el directorio de tu proyecto:

python -m venv .venv

En macOS o Linux, actívalo con:

source .venv/bin/activate

En Windows PowerShell, usa:

.venv\Scripts\Activate.ps1

Después instala la versión de esta guía:

python -m pip install "cartesia==4.2.0"

Si tu sistema usa python3 en lugar de python, usa ese comando para crear el entorno. Fijar la versión del SDK mantiene estables los nombres de los métodos del ejemplo. Cuando actualices, consulta las notas de versión del SDK para revisar los cambios.

Configura tu clave de API

Crea una clave de API en el entorno de pruebas de Cartesia. Concédele los permisos necesarios para generar texto a voz. Configura la clave en el terminal donde ejecutarás Python.

En macOS o Linux:

export CARTESIA_API_KEY="your-api-key"

En Windows PowerShell:

$env:CARTESIA_API_KEY = "your-api-key"

Sustituye your-api-key por tu propia clave. Trátala como una contraseña. No la incluyas en Git, la pegues en un cuaderno público ni la pongas en código del navegador. Para una aplicación desplegada, guárdala en el gestor de secretos del servidor. Si una clave se expone, revócala y crea otra.

Genera y guarda un archivo WAV

Guarda lo siguiente como speak.py:

import os
from pathlib import Path

from cartesia import Cartesia

api_key = os.environ.get("CARTESIA_API_KEY")
if not api_key:
    raise SystemExit("Set CARTESIA_API_KEY before running this script.")

output_path = Path("hello.wav")

with Cartesia(api_key=api_key) as client:
    response = client.tts.generate(
        model_id="sonic-latest",
        transcript="Hello from Python. Your first audio file is ready.",
        voice="e07c00bc-4134-4eae-9ea4-1a55fb45746b",
        output_format={
            "container": "wav",
            "encoding": "pcm_f32le",
            "sample_rate": 44100,
        },
    )
    response.write_to_file(output_path)

print(f"Saved audio to {output_path.resolve()}")

Ejecútalo desde el mismo terminal:

python speak.py

Tras una solicitud correcta, abre hello.wav en un reproductor que admita WAV con PCM de coma flotante. El script imprime la ruta completa para que no tengas que adivinar qué directorio usó Python. Guarda el audio, pero no lo reproduce automáticamente. Ejecutarlo de nuevo sobrescribe hello.wav y hace otra solicitud a la API.

La solicitud sigue el ejemplo de uso publicado del SDK.¹ El identificador de voz corresponde a la voz de ejemplo de esa referencia. Puedes sustituirlo por un identificador de voz disponible en tu cuenta.

Elige la voz, el modelo y el formato de audio

transcript es el texto que Sonic debe pronunciar. Empieza con una frase antes de enviar un documento largo. Usa texto que puedas enviar a la API y evita registrar transcripciones privadas en los registros de la aplicación.

voice selecciona al hablante. Prueba una frase en el generador de voz y usa el identificador de la voz elegida en la solicitud. Un nombre visible no es un identificador de voz. Si usas una voz clonada, asegúrate de tener permiso para usar la voz de esa persona.

El ejemplo usa sonic-latest, como la referencia del SDK. Un alias de modelo puede cambiar independientemente del SDK instalado. Para pruebas de producción reproducibles, elige un identificador de modelo específico compatible de la documentación de modelos y regístralo junto con el identificador de voz y el texto de prueba.

El formato de salida describe el archivo de audio:

El PCM sin procesar no tiene cabecera WAV. Cambiar su extensión a .wav no lo convierte en un archivo WAV. Si envías audio a un sistema telefónico u otro servicio, comprueba el contenedor, la codificación y la frecuencia de muestreo requeridos antes de generar voz.

Resuelve errores habituales

Cuando pidas ayuda, incluye las versiones de Python y del SDK, el código de estado y cualquier identificador de solicitud devuelto con el error. Elimina primero las claves de API y el texto privado.

Cuándo usar streaming

Guardar un WAV resulta útil para narraciones, locuciones y comprobaciones de integración. Una aplicación conversacional puede necesitar reproducir audio antes de que la respuesta completa esté lista o aceptar texto a medida que un LLM lo genera.

En ese caso, instala la compatibilidad con WebSocket en el mismo entorno:

python -m pip install "cartesia[websockets]==4.2.0"

Después empieza por el ejemplo de WebSocket con entrada en streaming del SDK.¹ También necesitas reproducción de audio, búferes y gestión de interrupciones. Escribir en disco los fragmentos que llegan no hace que la aplicación hable en tiempo real.

Cuando funcione el ejemplo breve, sustituye el texto por una frase de tu aplicación. Escucha nombres, números y abreviaturas antes de generar un lote mayor. Consulta los precios de la API y conserva los identificadores de modelo y voz con los resultados de las pruebas.