Sintesi vocale in Python: salva l'audio come file WAV

Per convertire testo in parlato in Python, invia un testo a un modello vocale e salva l’audio restituito. Questa guida usa l’SDK Python di Cartesia per generare un file WAV con Sonic.

Servono Python 3.9 o successivo, connessione internet e un account Cartesia con accesso API. L’esempio usa l’SDK versione 4.2.0.¹ Chiama un’API ospitata: il testo esce dal tuo computer. Per la sintesi offline, usa invece un motore vocale locale.

Installa l’SDK Python

Crea un ambiente virtuale nella directory del progetto:

python -m venv .venv

Su macOS o Linux, attivalo con:

source .venv/bin/activate

Su Windows PowerShell, usa:

.venv\Scripts\Activate.ps1

Poi installa la versione usata in questa guida:

python -m pip install "cartesia==4.2.0"

Se il sistema usa python3 anziché python, usa quel comando per creare l’ambiente. Fissare la versione dell’SDK mantiene stabili i nomi dei metodi dell’esempio. Quando aggiorni, consulta le note di rilascio dell’SDK per le modifiche.

Imposta la chiave API

Crea una chiave API nel Cartesia Playground. Assegnale i permessi necessari alla sintesi vocale. Impostala nel terminale da cui eseguirai Python.

Su macOS o Linux:

export CARTESIA_API_KEY="your-api-key"

Su Windows PowerShell:

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

Sostituisci your-api-key con la tua chiave. Trattala come una password: non salvarla in Git, non incollarla in un notebook pubblico e non inserirla nel codice browser. In un’applicazione distribuita, conservala nel gestore dei segreti del server. Se viene esposta, revocala e creane una nuova.

Genera e salva un file WAV

Salva questo codice come 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()}")

Eseguilo dallo stesso terminale:

python speak.py

Dopo una richiesta riuscita, apri hello.wav in un lettore che supporta WAV PCM a virgola mobile. Lo script stampa il percorso completo, quindi non devi indovinare quale directory abbia usato Python. Salva l’audio, ma non lo riproduce automaticamente. Eseguirlo di nuovo sovrascrive hello.wav ed effettua un’altra richiesta API.

La richiesta segue l’esempio d’uso pubblicato nell’SDK.¹ L’ID voce è quello dell’esempio di riferimento. Puoi sostituirlo con un ID voce disponibile nel tuo account.

Scegli voce, modello e formato audio

transcript è il testo che Sonic deve pronunciare. Parti da una frase prima di inviare un documento lungo. Usa testo che puoi inviare all’API ed evita di registrare trascrizioni private nei log applicativi.

voice seleziona chi parla. Prova una frase nel generatore di voci, poi usa l’ID della voce scelta nella richiesta. Il nome visualizzato non è un ID voce. Se usi una voce clonata, assicurati di avere il permesso di utilizzare la voce di quella persona.

L’esempio usa sonic-latest, come il riferimento dell’SDK. Un alias di modello può cambiare indipendentemente dall’SDK installato. Per test di produzione ripetibili, scegli un ID di modello supportato specifico dalla documentazione dei modelli e registralo insieme all’ID voce e al testo di prova.

Il formato di output descrive il file audio:

Il PCM grezzo non ha un’intestazione WAV. Rinominare un file PCM grezzo in .wav non lo trasforma in un WAV. Se invii audio a un sistema telefonico o altro servizio, verifica contenitore, codifica e frequenza di campionamento richiesti prima di generare il parlato.

Risolvi gli errori comuni

Quando chiedi aiuto, includi versioni di Python e SDK, codice di stato ed eventuale ID della richiesta restituito con l’errore. Rimuovi prima chiavi API e testo privato.

Quando usare invece lo streaming

Salvare un WAV è utile per narrazione, voiceover e verifica di un’integrazione. Un’applicazione conversazionale può dover riprodurre l’audio prima che sia pronta una risposta completa o accettare testo mentre un LLM lo genera.

In quel caso, installa il supporto WebSocket nello stesso ambiente:

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

Poi parti dall’esempio WebSocket con input in streaming dell’SDK.¹ Serviranno anche riproduzione audio, buffering e gestione delle interruzioni. Scrivere su disco i segmenti in arrivo non basta a far parlare l’applicazione in tempo reale.

Quando l’esempio breve funziona, sostituisci il testo con una frase della tua applicazione. Ascolta nomi, numeri e abbreviazioni prima di generare un lotto più grande. Controlla i prezzi API e conserva gli ID modello e voce con i risultati dei test.