Narração de Artigos com Texto para Fala

Fazer uma chamada ao /audio/speech é fácil. Narrar um artigo real é onde os problemas interessantes aparecem: o endpoint aceita no máximo 4096 caracteres por requisição, cada voz pertence a um modelo específico, os formatos de áudio diferem de modelo para modelo, e texto escrito para ser lido não se parece em nada com texto escrito para ser ouvido. Neste tutorial trabalhamos os quatro pontos. O resultado é um script que transforma uma URL em um único arquivo de áudio:

python article_to_audio.py https://docs.venice.ai/overview/privacy

Iremos:

Escolher um modelo e uma voz adequados para narração de textos longos
Fazer uma única requisição de fala e salvar o áudio
Dividir um artigo longo em pedaços que caibam no limite de caracteres
Unir os pedaços sintetizados em um único arquivo sem emendas audíveis
Reescrever o artigo em algo que valha a pena ouvir
Combinar as peças, e então dar uma olhada em streaming para uso interativo

Configuração

Você precisa do Python 3.9 ou mais recente, do pacote requests e de uma chave de API Venice.

pip install requests
export VENICE_API_KEY="your-api-key-here"

1. Escolha um modelo e uma voz

Vozes pertencem a modelos. Enviar uma voz de uma família para um modelo de outra é o erro inicial mais comum, então comece listando o que cada modelo realmente aceita:

curl "https://api.venice.ai/api/v1/models?type=tts" \
  -H "Authorization: Bearer $VENICE_API_KEY" |
  jq -r '.data[] | "\(.id)  formats=\(.model_spec.supported_formats)  voices=\(.model_spec.voices | length)"'

tts-kokoro  formats=["mp3","opus","aac","flac","wav","pcm"]  voices=54
tts-qwen3-1-7b  formats=["mp3"]  voices=9
tts-xai-v1  formats=["mp3","wav","pcm"]  voices=26
tts-inworld-1-5-max  formats=["wav"]  voices=14
tts-chatterbox-hd  formats=["wav"]  voices=9
tts-orpheus  formats=["wav"]  voices=8
tts-elevenlabs-turbo-v2-5  formats=["mp3"]  voices=21
tts-minimax-speech-02-hd  formats=["mp3","pcm","flac"]  voices=15
tts-gemini-3-1-flash  formats=["mp3","opus","wav"]  voices=30
tts-gradium-v1  formats=["wav","pcm","opus"]  voices=12

model_spec.voices é a lista autoritativa de vozes de um modelo, e supported_formats diz quais valores de response_format ele aceita. Remova o | length da consulta para imprimir os nomes das vozes. Vamos usar tts-xai-v1 com a voz eve. Ele suporta pcm, o que torna a união dos pedaços simples na seção 4.

A velocidade de síntese varia muito mais entre modelos TTS do que a qualidade da saída, e a diferença é grande o suficiente para mudar sua arquitetura. Meça uma requisição realista contra dois ou três candidatos antes de se comprometer. Um pedaço que um modelo retorna em poucos segundos pode levar vários minutos em outro.

2. Faça uma única requisição

O corpo da resposta é áudio bruto, e não JSON, então escreva os bytes diretamente em um arquivo.

import os
from pathlib import Path

import requests

response = requests.post(
    "https://api.venice.ai/api/v1/audio/speech",
    headers={
        "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "tts-xai-v1",
        "voice": "eve",
        "input": "Hello from Venice.",
        "response_format": "mp3",
    },
    timeout=300,
)

response.raise_for_status()
Path("hello.mp3").write_bytes(response.content)

import { writeFile } from "node:fs/promises";

const response = await fetch("https://api.venice.ai/api/v1/audio/speech", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.VENICE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "tts-xai-v1",
    voice: "eve",
    input: "Hello from Venice.",
    response_format: "mp3",
  }),
});

if (!response.ok) {
  throw new Error(`${response.status}: ${await response.text()}`);
}

await writeFile("hello.mp3", Buffer.from(await response.arrayBuffer()));

curl https://api.venice.ai/api/v1/audio/speech \
  -H "Authorization: Bearer $VENICE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-xai-v1",
    "voice": "eve",
    "input": "Hello from Venice.",
    "response_format": "mp3"
  }' \
  --output hello.mp3

Combinações incompatíveis são rejeitadas antes que qualquer áudio seja gerado, e o erro indica o que teria funcionado:

{"error":"Voice \"eve\" is not supported by model \"tts-kokoro\". Try using a supported voice: af_alloy, af_aoede, af_bella, af_heart, af_jadzia, ...."}

{"error":"response_format \"wav\" is not supported by model \"tts-elevenlabs-turbo-v2-5\". Supported formats: mp3."}

3. Divida o texto no limite de 4096 caracteres

O campo input aceita no máximo 4096 caracteres. Textos mais longos são rejeitados imediatamente, em vez de silenciosamente truncados:

{"error":"Invalid request parameters","issues":[{"code":"too_big","maximum":4096,"path":["input"]}]}

Portanto, dividimos o artigo primeiro. Dividir em fronteiras de frase importa, porque um pedaço que termina no meio de uma frase produz um tropeço audível na junção. Crie narrate.py:

from __future__ import annotations

import os
import re
import sys
import wave
from concurrent.futures import ThreadPoolExecutor

import requests

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

MODEL = "tts-xai-v1"
VOICE = "eve"
SAMPLE_RATE = 24000  # tts-xai-v1 returns 24 kHz mono signed 16-bit PCM.

SENTENCE_END = re.compile(r"(?<=[.!?])\s+")


def split_into_chunks(text: str, max_chars: int = 1500) -> list[str]:
    """Split text on sentence boundaries into chunks under the 4096-character cap."""
    chunks: list[str] = []
    current = ""

    for sentence in SENTENCE_END.split(text.strip()):
        if not sentence:
            continue
        if len(sentence) > max_chars:
            raise ValueError(f"Sentence longer than {max_chars} characters: {sentence[:80]}...")
        if len(current) + len(sentence) + 1 > max_chars:
            chunks.append(current)
            current = sentence
        else:
            current = f"{current} {sentence}" if current else sentence

    if current:
        chunks.append(current)
    return chunks

Em um roteiro de 5362 caracteres, isso produz quatro pedaços, cada um terminando em uma frase:

chunks = split_into_chunks(script)
print(f"len(chunks) = {len(chunks)}")
for index, chunk in enumerate(chunks):
    print(f"chunk {index}: {len(chunk)} chars")

len(chunks) = 4
chunk 0: 1428 chars
chunk 1: 1410 chars
chunk 2: 1489 chars
chunk 3: 1015 chars

O max_chars padrão é 1500, e não algo próximo do teto de 4096, e isso é intencional. O tempo de síntese cresce com o comprimento da entrada, então pedaços menores retornam mais cedo e, como executam em paralelo, terminam o trabalho todo mais rápido. Eles também tornam as tentativas de repetição baratas quando uma requisição falha.

4. Una os pedaços em um único arquivo

Concatenar áudio codificado como MP3 é pouco confiável, porque cada pedaço carrega seus próprios cabeçalhos de frame. Solicitar pcm evita o problema por completo. PCM é composto por amostras brutas sem contêiner, então unir é apenas concatenar bytes, e o módulo wave da biblioteca padrão do Python escreve o cabeçalho para nós.

def synthesize(text: str, speed: float = 1.0) -> bytes:
    """Return raw PCM audio for one chunk."""
    response = requests.post(
        f"{BASE_URL}/audio/speech",
        headers=HEADERS,
        json={
            "model": MODEL,
            "voice": VOICE,
            "input": text,
            "response_format": "pcm",
            "speed": speed,
        },
        timeout=300,
    )
    if response.status_code != 200:
        raise RuntimeError(f"TTS failed ({response.status_code}): {response.text}")
    return response.content


def narrate(text: str, out_path: str) -> str:
    chunks = split_into_chunks(text)
    print(f"Synthesizing {len(chunks)} chunks", file=sys.stderr)

    with ThreadPoolExecutor(max_workers=4) as pool:
        audio = list(pool.map(synthesize, chunks))

    with wave.open(out_path, "wb") as output:
        output.setnchannels(1)
        output.setsampwidth(2)
        output.setframerate(SAMPLE_RATE)
        for part in audio:
            output.writeframes(part)

    seconds = sum(len(part) for part in audio) / 2 / SAMPLE_RATE
    print(f"Wrote {out_path} ({seconds:.1f}s of audio)", file=sys.stderr)
    return out_path

Um único pedaço retorna rapidamente em relação à quantidade de áudio que contém:

pcm = synthesize(chunks[0])
print(f"bytes   = {len(pcm)}")
print(f"audio   = {len(pcm) / 2 / SAMPLE_RATE:.1f}s")

bytes   = 4269376
audio   = 88.9s

Essa requisição levou cerca de 13 segundos para produzir 89 segundos de fala. Executar os quatro pedaços simultaneamente é o que mantém o total razoável: a narração completa abaixo levou 15 segundos de tempo real. ThreadPoolExecutor.map retorna os resultados na ordem em que as entradas foram submetidas, então os pedaços chegam em ordem de leitura mesmo tendo sido sintetizados ao mesmo tempo.

PCM bruto não carrega taxa de amostragem, então você precisa informar a correta ao escrever o cabeçalho WAV, e ela é específica do modelo. tts-xai-v1 retorna 24 kHz, enquanto tts-gradium-v1 retorna 48 kHz. Errar isso faz a narração tocar na velocidade e no tom errados.

Para descobrir a taxa de qualquer modelo, peça um clipe curto como wav e leia o cabeçalho que ele devolve:

import wave

response = requests.post(
    f"{BASE_URL}/audio/speech",
    headers=HEADERS,
    json={"model": MODEL, "voice": VOICE, "input": "Probe.", "response_format": "wav"},
    timeout=300,
)
response.raise_for_status()
with open("probe.wav", "wb") as handle:
    handle.write(response.content)

with wave.open("probe.wav") as probe:
    print(probe.getframerate(), probe.getnchannels(), probe.getsampwidth())

24000 1 2

5. Prepare o texto para soar bem

Markdown extraído lido em voz alta literalmente é quase impossível de escutar. URLs são o exemplo mais claro. Um modelo de fala soletra caractere por caractere, então https://docs.venice.ai/llms.txt sai como:

h t t p s dois-pontos barra barra docs ponto venice ponto a i l l m s ponto t x t

Cabeçalhos, marcadores de lista, tabelas e blocos de código causam versões menores do mesmo problema. Em vez de brigar com Markdown usando expressões regulares, podemos pedir a um modelo de chat que reescreva o artigo como algo destinado a ser falado. Crie article_to_audio.py:

from __future__ import annotations

import os
import re
import sys

import requests

from narrate import narrate

BASE_URL = "https://api.venice.ai/api/v1"
HEADERS = {
    "Authorization": f"Bearer {os.environ['VENICE_API_KEY']}",
    "Content-Type": "application/json",
}

URL_PATTERN = re.compile(r"https?://\S+|www\.\S+")


def scrape(url: str) -> str:
    response = requests.post(
        f"{BASE_URL}/augment/scrape", headers=HEADERS, json={"url": url}, timeout=120
    )
    response.raise_for_status()
    return response.json()["content"]


def write_script(markdown: str, minutes: int = 6) -> str:
    response = requests.post(
        f"{BASE_URL}/chat/completions",
        headers=HEADERS,
        json={
            "model": "zai-org-glm-5-1",
            "messages": [
                {
                    "role": "system",
                    "content": (
                        "You rewrite articles as scripts to be read aloud. Output plain prose only: "
                        "no Markdown, no headings, no bullet points, no URLs, no code, no emoji. "
                        "Spell out abbreviations and numbers the way a narrator would say them. "
                        "Use short sentences with clear punctuation so speech synthesis paces well."
                    ),
                },
                {
                    "role": "user",
                    "content": f"Rewrite this article as a {minutes}-minute spoken summary.\n\n{markdown[:20000]}",
                },
            ],
            "temperature": 0.4,
        },
        timeout=300,
    )
    response.raise_for_status()
    script = response.json()["choices"][0]["message"]["content"]
    return URL_PATTERN.sub("", script).strip()

A substituição URL_PATTERN fica como rede de segurança para o link ocasional que o modelo deixe passar.

6. Juntando tudo

O ponto de entrada faz o scrape, escreve o roteiro, o salva e narra:

if __name__ == "__main__":
    url = sys.argv[1]

    print("Scraping", url, file=sys.stderr)
    markdown = scrape(url)

    print(f"Writing script from {len(markdown)} characters of Markdown", file=sys.stderr)
    script = write_script(markdown)

    with open("script.txt", "w") as handle:
        handle.write(script)

    narrate(script, "article.wav")

Salvar script.txt ao lado do áudio vale as duas linhas. Quando uma narração soa errada, o roteiro quase sempre mostra por quê, e você pode corrigir sem pagar para sintetizar de novo.

python article_to_audio.py https://docs.venice.ai/overview/privacy

Scraping https://docs.venice.ai/overview/privacy
Writing script from 7582 characters of Markdown
Synthesizing 4 chunks
Wrote article.wav (355.0s of audio)

Pouco menos de seis minutos de narração, produzidos em cerca de quinze segundos. O roteiro agora começa com prosa em vez de elementos de navegação:

Venice is built on a simple but powerful principle. User privacy comes first. The platform’s entire architecture flows from this philosophical commitment.

Para verificar uma narração sem precisar ouvi-la inteira, envie o áudio de volta por /audio/transcriptions e compare a transcrição com script.txt. Transcrever os últimos vinte segundos é uma maneira rápida de confirmar que os pedaços foram unidos na ordem correta, e pega pedaços perdidos e URLs soletradas em segundos.

Streaming para uso interativo

A narração em lote otimiza o tempo total. Uma interface de voz tem a prioridade oposta, que é entregar o primeiro áudio o mais rápido possível. Definir streaming: true retorna o corpo frase a frase à medida que é gerado, então a reprodução pode começar em cerca de um segundo em vez de esperar pelo clipe completo.

import time

import requests

start = time.time()
first_byte = None

with requests.post(
    "https://api.venice.ai/api/v1/audio/speech",
    headers=HEADERS,
    json={
        "model": "tts-xai-v1",
        "voice": "eve",
        "input": "Streaming returns audio while the rest is still being generated.",
        "response_format": "mp3",
        "streaming": True,
    },
    stream=True,
    timeout=300,
) as response:
    response.raise_for_status()
    with open("streamed.mp3", "wb") as audio:
        for chunk in response.iter_content(chunk_size=4096):
            if first_byte is None:
                first_byte = time.time() - start
            audio.write(chunk)

print(f"first byte: {first_byte:.2f}s   complete: {time.time() - start:.2f}s")

first byte: 0.85s   complete: 1.43s

Prefira pcm a mp3 quando estiver alimentando a Web Audio API de um navegador ou um dispositivo de áudio diretamente, pois não precisa de etapa de decodificação.

Opções de requisição que vale a pena conhecer

Parâmetro	Notas
`speed`	Aceita `0.25` a `4.0`, padrão `1.0`. Fique aproximadamente entre `0.8` e `1.3` para narração. Além disso, a entrega deixa de soar natural.
`language`	Dica opcional cuja forma aceita é específica do modelo. xAI e ElevenLabs recebem códigos ISO 639-1 como `en`, enquanto Qwen 3 e MiniMax recebem nomes completos como `English`. Valores não suportados são ignorados.
`prompt`	Dica de estilo e emoção, com até 500 caracteres, atualmente respeitada apenas pelos modelos Qwen 3. Para outras famílias, a escolha da voz carrega o tom.
`temperature`	Faixa `0` a `2`, suportada por Qwen 3, Orpheus e Chatterbox HD. Aumente para obter mais variação entre takes.

Erros

Status	Causa	Correção
`400`	`input` com mais de 4096 caracteres	Divida o texto em pedaços como na seção 3
`400`	Voz inválida para o modelo	Use uma voz do `model_spec.voices` daquele modelo
`400`	Formato não suportado pelo modelo	Verifique `model_spec.supported_formats`
`401`	Chave ausente ou inválida	Confirme o cabeçalho `Authorization: Bearer`
`402`	Saldo insuficiente	Recarregue a conta
`429`	Limite de taxa atingido	Reduza `max_workers` e refaça com backoff
`500` ou `503`	Falha de capacidade ou de inferência	Refaça o pedaço afetado com jitter

Como os pedaços são independentes, uma falha custa no máximo um deles, e refazer synthesize para esse pedaço é sempre seguro.

Próximos passos

Algumas extensões naturais a partir daqui:

Faça cache do áudio por um hash do texto, voz e modelo, para que parágrafos inalterados nunca sejam sintetizados novamente.
Substitua por uma voz clonada com Clonagem de Voz, para que a narração use a sua própria.
Gere o texto de origem em vez de fazer scrape, usando Respostas com Citações usando Web Search.
Adicione áudio de introdução ou de fundo com Música e Efeitos Sonoros.

Texto para Fala

Referência para o endpoint de fala e seus parâmetros.

Clonagem de Voz

Narre com uma voz personalizada em vez de uma predefinida.

Respostas com Citações usando Web Search

Gere o texto que esta ferramenta narra.

Fala para Texto

Transcreva áudio para verificar uma narração de ponta a ponta.

Documentação

Primeiros passos

Texto e chat

Imagem

Vídeo

Áudio

Pesquisa e RAG

Agentes e integrações

Ferramentas de código

Ferramentas para agentes

SDKs e frameworks

Narração de Artigos com Texto para Fala

Configuração

1. Escolha um modelo e uma voz

2. Faça uma única requisição

3. Divida o texto no limite de 4096 caracteres

4. Una os pedaços em um único arquivo

5. Prepare o texto para soar bem

6. Juntando tudo

Streaming para uso interativo

Opções de requisição que vale a pena conhecer

Erros

Próximos passos

Texto para Fala

Clonagem de Voz

Respostas com Citações usando Web Search

Fala para Texto

​Configuração

​1. Escolha um modelo e uma voz

​2. Faça uma única requisição

​3. Divida o texto no limite de 4096 caracteres

​4. Una os pedaços em um único arquivo

​5. Prepare o texto para soar bem

​6. Juntando tudo

​Streaming para uso interativo

​Opções de requisição que vale a pena conhecer

​Erros

​Próximos passos

Texto para Fala

Clonagem de Voz

Respostas com Citações usando Web Search

Fala para Texto

Configuração

1. Escolha um modelo e uma voz

2. Faça uma única requisição

3. Divida o texto no limite de 4096 caracteres

4. Una os pedaços em um único arquivo

5. Prepare o texto para soar bem

6. Juntando tudo

Streaming para uso interativo

Opções de requisição que vale a pena conhecer

Erros

Próximos passos