Para converter texto em fala em Python, envie uma transcrição a um modelo e salve o áudio retornado. Este guia usa o SDK Python da Cartesia para gerar um WAV com Sonic.
Você precisa de Python 3.9 ou superior, internet e uma conta Cartesia com acesso à API. O exemplo usa o SDK 4.2.0.1 Ele chama uma API hospedada, então o texto sai da máquina. Para síntese offline, use um mecanismo local.
Instale o SDK Python
Crie um ambiente virtual no diretório do projeto:
python -m venv .venvNo macOS ou Linux, ative-o com:
source .venv/bin/activateNo Windows PowerShell, use:
.venv\Scripts\Activate.ps1Instale a versão usada no guia:
python -m pip install "cartesia==4.2.0"Se seu sistema usa python3 em vez de python, use esse comando para criar o ambiente. Fixar a versão mantém os nomes dos métodos estáveis. Ao atualizar, confira as notas de versão do SDK.
Configure a chave de API
Crie uma chave no Cartesia Playground com as permissões necessárias para gerar fala. Defina-a no terminal em que executará Python.
No macOS ou Linux:
export CARTESIA_API_KEY="your-api-key"No Windows PowerShell:
$env:CARTESIA_API_KEY = "your-api-key"Substitua your-api-key pela sua chave. Trate-a como uma senha. Não a envie ao Git, a um notebook público ou ao código do navegador. Em produção, armazene-a no gerenciador de segredos do servidor. Se for exposta, revogue-a e crie outra.
Gere e salve um WAV
Salve este código 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()}")Execute no mesmo terminal:
python speak.pyApós uma solicitação bem-sucedida, abra hello.wav em um reprodutor compatível com WAV PCM de ponto flutuante. O script imprime o caminho completo, evitando dúvida sobre o diretório. Ele salva, mas não reproduz automaticamente. Executá-lo novamente sobrescreve hello.wav e faz outra solicitação à API.
A solicitação segue o exemplo publicado do SDK.1 O ID de voz vem dessa referência. Você pode trocá-lo por um ID disponível na sua conta.
Escolha voz, modelo e formato
transcript é o texto que Sonic deve falar. Comece com uma frase antes de enviar um documento longo. Use texto que você pode enviar à API e evite registrar transcrições privadas nos logs.
voice seleciona a voz. Teste uma frase no gerador de voz e use o ID escolhido na solicitação. Nome de exibição não é ID. Para vozes clonadas, confirme que tem permissão da pessoa.
O exemplo usa sonic-latest, como a referência do SDK. Um alias pode mudar independentemente do SDK instalado. Para testes reproduzíveis em produção, escolha um ID específico compatível na documentação de modelos e registre-o com o ID da voz e o texto.
O formato de saída descreve o arquivo:
| Campo | Valor no exemplo | Significado |
|---|---|---|
container | wav | Coloca o áudio em um WAV com cabeçalho. |
encoding | pcm_f32le | Armazena amostras PCM de ponto flutuante de 32 bits, little-endian. |
sample_rate | 44100 | Usa 44,100 amostras por segundo. |
PCM bruto não tem cabeçalho WAV. Renomeá-lo para .wav não o transforma em WAV. Para enviar áudio à telefonia ou a outro serviço, confira contêiner, codificação e taxa de amostragem exigidos antes de gerar.
Resolva erros comuns
| Sintoma | O que verificar |
|---|---|
ModuleNotFoundError: No module named 'cartesia' | Ative o ambiente em que instalou o SDK. Execute python -m pip show cartesia com o mesmo interpretador do script. |
Set CARTESIA_API_KEY before running this script. | Defina a variável no terminal atual e execute novamente. Editor ou notebook podem usar outro ambiente. |
| Erro de autenticação ou permissão | Confirme que a chave está ativa, pertence à conta certa e tem as permissões necessárias. Nunca a inclua no relatório de erro. |
| Erro de modelo, voz ou formato | Confira a referência atual e a disponibilidade da voz na conta. Copie os IDs exatamente. |
| Erro de limite de taxa | Confira os limites e reduza a concorrência. Evite um ciclo de novas tentativas imediatas. |
AttributeError envolvendo generate | Confira a versão instalada. Exemplos antigos podem usar client.tts.bytes. Este guia usa client.tts.generate na versão 4.2.0. |
| O arquivo existe, mas não reproduz | Confirme container="wav", suporte do reprodutor a PCM de ponto flutuante e que o arquivo não está vazio. |
Ao pedir ajuda, informe versões de Python e SDK, código de status e ID da solicitação retornado. Remova antes chaves e texto privado.
Quando usar streaming
Salvar WAV é útil para narração, locução e testes de integração. Uma aplicação conversacional pode precisar reproduzir antes de a resposta completa ficar pronta ou receber texto conforme o LLM o gera.
Nesse caso, instale o suporte WebSocket no mesmo ambiente:
python -m pip install "cartesia[websockets]==4.2.0"Comece pelo exemplo de entrada em streaming via WebSocket.1 Você também precisará de reprodução, buffers e tratamento de interrupções. Gravar os segmentos recebidos em disco não faz a aplicação falar em tempo real.
Quando o exemplo curto funcionar, use uma frase da sua aplicação. Ouça nomes, números e abreviações antes de gerar um lote maior. Confira os preços da API e guarde os IDs de modelo e voz com os resultados.
Notas de rodapé
-
Cartesia, SDK Python 4.2.0 no PyPI e referência de uso do SDK, consultados em 13 de setembro de 2026. ↩ ↩2 ↩3