Documentação Completa da API de Síntese de Voz por Texto

Por Equ editorial VozPublica · Atualizado 2026-11-19

Esta documentação técnica detalha a integração da API VozPublica, projetada especificamente para agências de publicidade e produção de rádio. Aqui você encontra a referência para transformar roteiros em áudio via endpoints RESTful, seguindo o padrão do endpoint de speech da OpenAI para facilitar a adoção imediata.

Utilize este guia para configurar autenticação, selecionar vozes, definir formatos de saída e gerenciar limites de taxa. Exemplos de código, descrições de parâmetros e tratamentos de erro estão organizados para permitir a implementação rápida em seus pipelines de geração de spots publicitários, garantindo escalabilidade e controle técnico preciso.

Documentação Completa da API de Síntese de Voz por Texto

Perguntas frequentes

Como obter a chave API?

Acesse /get-api-key/ para criar uma conta via Google ou e-mail/senha. Após o registro, a página exibe sua chave API ativa, saldo e um exemplo de curl. A autenticação usa o cabeçalho Authorization: Bearer tts-... . Uma nova chave substitui a anterior imediatamente.

Qual a estrutura do JSON de entrada?

Envie um POST para /v1/audio/speech com o corpo JSON contendo: model ("tts-1" ou "tts-1-hd"), input (texto até 4096 caracteres), voice (um dos 8 presets), response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) e language (opcional, código ISO).

Posso usar o SDK oficial da OpenAI?

Sim. Os SDKs oficiais da OpenAI funcionam alterando o base_url para https://api.bpexc.info/v1 e usando sua chave API. A estrutura da requisição é idêntica ao endpoint de fala da OpenAI, permitindo integração rápida sem necessidade de uma SDK própria.

Como definir o idioma da voz?

Defina o campo language com o código ISO desejado. Se não especificado, o idioma é inferido pelo script (texto latino padrão para inglês). Para textos em latino não ingleses, defina language explicitamente. O sistema suporta 23 idiomas específicos, como português, espanhol e francês.

Qual o limite máximo de caracteres?

Cada requisição aceita até 4096 caracteres. Espaços e pontuação contam como caracteres. Para textos maiores, divida o conteúdo em partes de até 4096 caracteres e junte os arquivos de áudio resultantes. O limite é por chamada de API, não pelo texto total.

O que são os códigos de erro?

Requisições falhas são gratuitas e o valor é estornado integralmente. O sistema retorna códigos de erro padrão HTTP para indicar falhas de autenticação, limites de taxa ou erros de formato. Verifique a resposta JSON para detalhes específicos da falha na síntese.

Como gerar áudio em WAV?

Inclua o campo response_format com o valor "wav" no corpo da requisição JSON. O formato WAV é um dos cinco formatos suportados, junto com mp3, opus, flac e pcm. O arquivo de áudio será retornado diretamente na resposta da API.

Posso alterar a velocidade da voz?

Sim, use o campo speed com valores entre 0.25 e 4.0. O padrão é 1.0. Isso permite acelerar ou desacelerar a fala para ajustar o ritmo do anúncio. A velocidade afeta apenas a duração da geração, mantendo a qualidade do áudio.

A chave API pode ser revogada?

Sim. Uma nova chave pode ser emitida a qualquer momento na página de gerenciamento. Ao emitir uma nova chave, a anterior deixa de funcionar imediatamente. Isso permite revogação instantânea em caso de uso indevido ou troca de equipe sem esperar expiração.

Quanto tempo dura uma requisição?

O tempo varia conforme a carga do sistema. Em geral, gera-se cerca de 25 caracteres de texto por segundo de áudio gerado. Frases curtas levam alguns segundos. Sob carga, as requisições podem aguardar na fila, pois são processadas sequencialmente.

Os dados de entrada são armazenados?

O texto de entrada é usado apenas para produzir o áudio e não é utilizado para treinamento. O áudio gerado é retornado na resposta e não é armazenado. Apenas metadados da requisição (tempo, caracteres, status) são mantidos para fins de faturamento.

Como lidar com textos longos?

Divida o texto em partes de até 4096 caracteres. Envie cada parte separadamente via API e junte os arquivos de áudio resultantes. Isso garante que cada requisição esteja dentro do limite permitido. Scripts de integração podem automatizar essa divisão e concatenação.

Existe limite de velocidade (speed)?

Sim, o campo speed aceita valores de 0.25 a 4.0. Valores fora desse intervalo podem ser rejeitados. Isso permite ajustar a velocidade da voz sintetizada para melhor adequação ao ritmo do spot publicitário, sem alterar a entonação da voz selecionada.

O formato PCM é suportado?

Sim, PCM é um dos formatos suportados, ao lado de mp3, wav, opus e flac. Selecione "pcm" no campo response_format da requisição. O formato PCM é útil para processamento posterior ou quando se deseja controle total sobre o stream de áudio.

Primeira solicitação

curl

curl https://api.bpexc.info/v1/audio/speech \
  -H "Authorization: Bearer $TTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model":"tts-1","voice":"aria","input":"Hello from the API.","response_format":"mp3"}' \
  --output hello.mp3

Python (openai)

from openai import OpenAI

client = OpenAI(base_url="https://api.bpexc.info/v1", api_key="tts-...")

with client.audio.speech.with_streaming_response.create(
    model="tts-1", voice="nova", input="Hello from Python.", response_format="mp3"
) as response:
    response.stream_to_file("hello.mp3")

Node.js (openai)

import OpenAI from "openai";
import fs from "node:fs";

const client = new OpenAI({ baseURL: "https://api.bpexc.info/v1", apiKey: process.env.TTS_API_KEY });
const res = await client.audio.speech.create({ model: "tts-1", voice: "milo", input: "Hello from Node.js." });
fs.writeFileSync("hello.mp3", Buffer.from(await res.arrayBuffer()));
voice
ariafeminino
novafeminino
lunafeminino
sagefeminino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Autenticação

Ilustração de onda sonora para: Autenticação

Para utilizar a API de síntese de voz, é necessário gerar uma chave de acesso única diretamente no painel de controle da conta. Cada conta mantém apenas uma chave ativa por vez, garantindo segurança e simplicidade na gestão dos acessos.

A autenticação é realizada exclusivamente via header HTTP, sem necessidade de bibliotecas adicionais ou tokens complexos. A chave identificada pelo prefixo "tts-" deve ser incluída em cada requisição para validar as chamadas à API.

Geração de chave

Geração de chave

Acesse a página /get-api-key/ para visualizar e gerenciar sua chave. O painel exibe o código ativo, o saldo atual e o histórico de uso. A chave é vinculada à conta criada via Google ou e-mail.

Header Authorization

Header Authorization

Inclua o cabeçalho Authorization: Bearer tts-<sua-chave> em todas as requisições POST e GET. O sistema valida a chave antes de processar o texto. Certifique-se de que não há espaços extras na string da chave.

Rotação de chave

Gere uma nova chave diretamente no painel a qualquer momento. A chave antiga é invalidada instantaneamente, sem período de transição. Utilize esta funcionalidade se houver suspeita de exposição ou para rotinação de segurança básica.

Endpoints Principais

Ilustração de onda sonora para: Endpoints Principais

O endpoint principal converte texto em áudio sintetizado. Consulte a estrutura de voz, idiomas e formatos disponíveis via GET /v1/voices e verifique os modelos ativos em GET /v1/models.

POST /v1/audio/speech

Recebe texto (até 4096 caracteres) e retorna arquivo de áudio. Suporta formatos mp3, wav, opus, flac ou pcm.

  • Endpoint: POST https://api.bpexc.info/v1/audio/speech
  • Body: JSON com model, input, voice, response_format

GET /v1/voices

Retorna lista das 8 vozes disponíveis, idiomas suportados e formatos de áudio compatíveis com cada voz.

GET /v1/models

Lista os modelos tts-1 e tts-1-hd com mesma engine e preço. Use base_url padrão da OpenAI SDK.

  • Modelos: tts-1, tts-1-hd

Primeira Requisição

Ilustração de onda sonora para: Primeira Requisição

A integração imediata valida a conexão e a autenticidade da chave. Utilize o comando curl abaixo para enviar um texto curto e receber o áudio sintetizado em formato MP3.

Este teste confirma que o endpoint responde corretamente e que o saldo da conta foi debitado conforme a tarifa padrão de $0,01 por mil caracteres.

Exemplo curl

Execute esta solicitação HTTP POST diretamente no terminal para gerar o primeiro arquivo de áudio.

  • curl -X POST "https://api.bpexc.info/v1/audio/speech" \
  • -H "Authorization: Bearer tts-seu-chave-aqui" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Olá, este é um teste da API VozPublica.", "voice": "aria", "response_format": "mp3"}' \
  • -o output.mp3

JSON body

O corpo da requisição deve ser um objeto JSON contendo o texto a ser sintetizado e a configuração do modelo.

  • "model": "tts-1" ou "tts-1-hd"
  • "input": string com até 4096 caracteres
  • "voice": um dos 8 presets disponíveis
  • "response_format": "mp3", "wav", "opus", "flac" ou "pcm"
  • "speed": número entre 0.25 e 4.0
  • "language": código ISO opcional

Resposta binária

Em caso de sucesso, o corpo da resposta contém os bytes brutos do arquivo de áudio. O campo Content-Type indica o formato enviado.

Integração com SDK

Ilustração de onda sonora para: Integração com SDK

O SDK da OpenAI funciona diretamente com nossa API, bastando ajustar a URL base. Isso permite reutilizar bibliotecas já conhecidas pela sua equipe de engenharia sem precisar aprender uma nova interface.

A configuração é mínima: aponte o cliente para o endpoint da VozPublica e utilize sua chave de API para autenticação. O formato das requisições segue o padrão padrão de síntese de áudio.

Base URL OpenAI

Utilize https://api.bpexc.info/v1 como base_url no seu cliente SDK. Isso redireciona as chamadas para nossa infraestrutura enquanto mantém a compatibilidade com o formato JSON do endpoint de fala.

  • URL: https://api.bpexc.info/v1
  • Formato: JSON padrão OpenAI
  • Compatível com SDKs oficiais

Configuração do cliente

Defina o cabeçalho Authorization: Bearer SUA_CHAVE_AQUI para autenticar cada requisição. A chave é gerada na sua conta e deve ser mantida em variáveis de ambiente para segurança.

Não é necessário alterar a estrutura do payload. O SDK cuida da serialização JSON para o corpo da requisição.

  • Header: Authorization: Bearer <key>
  • Envio de JSON padrão
  • Sem bibliotecas adicionais necessárias

Método de síntese

Chame o método de síntese passando o texto, o modelo (tts-1 ou tts-1-hd) e a voz desejada. O SDK enviará a requisição e retornará o áudio binário.

O áudio é entregue no formato solicitado (mp3, wav, opus, flac ou pcm). Processos batch devem lidar com o retorno binário conforme a linguagem de programação.

  • Método: POST /v1/audio/speech
  • Retorno: arquivo binário
  • Formatos: mp3, wav, opus, flac, pcm

Parâmetros de Entrada

Ilustração de onda sonora para: Parâmetros de Entrada

O parâmetro model aceita tts-1 ou tts-1-hd, utilizando o mesmo motor de síntese para ambos. A escolha da voice define a timbre vocal entre oito presets fixos, como aria para narração clara ou atlas para tom neutro de notícias. Cada voz suporta qualquer um dos 23 idiomas listados na API, garantindo consistência acústica independente do idioma.

A especificação do response_format controla o container de áudio retornado (mp3, wav, opus, flac, pcm), enquanto speed ajusta a taxa de fala entre 0.25 e 4.0. O parâmetro language é opcional; se omitido, o sistema tenta inferir pelo script, mas para textos em latim não ingleses, sua definição explícita é recomendada para precisão.

Modelo e voz

O campo model aceita apenas tts-1 ou tts-1-hd, ambos operando no mesmo motor de síntese com preço idêntico. A seleção de voice determina a timbre entre oito presets: aria, nova, luna, sage (femininas) e felix, milo, atlas, orion (masculinas).

Cada voz é capaz de pronunciar qualquer um dos 23 idiomas suportados. A escolha deve considerar o contexto do spot publicitário: atlas para tom neutro e informativo, felix para energia promocional ou aria para narração clara.

  • tts-1 e tts-1-hd compartilham o mesmo motor e preço

Formato de resposta

O parâmetro response_format define o container do arquivo de áudio retornado na resposta binária. As opções disponíveis são mp3, wav, opus, flac e pcm.

A escolha do formato deve considerar a compatibilidade do player de rádio ou sistema de automação da agência. MP3 e WAV são amplamente suportados, enquanto FLAC e OPUS oferecem compressão sem perdas ou alta eficiência.

Velocidade e idioma

O parâmetro speed ajusta a taxa de fala entre 0.25 e 4.0. Valores padrão produzem uma velocidade próxima à real (aproximadamente 25 caracteres por segundo).

O campo language é opcional. Se não fornecido, o sistema infere o idioma pelo script (texto latino assume inglês por padrão). Para textos em latim que não sejam inglês, defina language explicitamente para garantir a pronúncia correta.

Parâmetros de Entrada

Limites e Erros

Ilustração de onda sonora para: Limites e Erros

A API impõe limites técnicos claros para garantir estabilidade. Cada requisição POST aceita no máximo 4096 caracteres de entrada. Textos maiores devem ser divididos pelo cliente e as partes unidas posteriormente.

4096 caracteres

O campo input aceita até 4.096 caracteres por chamada. Espaços e pontuação contam como caracteres. Para roteiros longos, a lógica de divisão deve ser implementada no lado do cliente, concatenando os arquivos de áudio resultantes.

60 requisições/minuto

O limite padrão é de 60 requisições por minuto por chave de API. Contas novas ou sem recarga iniciam com 10 requisições/min. O processamento é sequencial, podendo haver filas sob carga.

Códigos de erro comuns

Erros de rate limit (429) indicam exceder o limite de 60 rpm. Erros de entrada (400) ocorrem se o modelo ou voz forem inválidos. Falhas de síntese são gratuitas e o saldo é estornado automaticamente.

  • Código 400: Parâmetros inválidos ou formato incorreto.
  • Código 401: Chave de API ausente ou inválida.
  • Código 429: Limite de 60 requisições/minuto excedido.
  • Código 500: Falha interna na síntese (saldo estornado).

Formatos de Áudio

Ilustração de onda sonora para: Formatos de Áudio

A API oferece cinco formatos de saída para atender às necessidades de infraestrutura e compatibilidade de cada cliente. A escolha do formato impacta diretamente o tamanho do arquivo e a latência na entrega final.

MP3 e WAV

MP3 é o padrão para a maioria das integrações web e mobile, oferecendo compactação eficiente com boa fidelidade. WAV fornece áudio não comprimido, ideal para edições subsequentes ou sistemas que exigem latência zero na decodificação.

  • MP3: compactação leve, amplamente compatível
  • WAV: áudio linear sem perdas

Opus e FLAC

Opus entrega alta qualidade com tamanho de arquivo reduzido, sendo excelente para streaming ou armazenamento de longo prazo. FLAC oferece compressão sem perdas, mantendo a integridade exata do sinal original para arquivamento profissional.

  • Opus: alta eficiência de compressão
  • FLAC: qualidade lossless preservada

PCM bruto

PCM retorna dados de áudio não comprimidos em formato linear. Este formato é ideal para pipelines de processamento que necessitam de acesso direto aos dados brutos de amostragem sem sobrecarga de decodificação.

  • PCM: dados lineares sem compressão

Tratamento de Erros

Ilustração de onda sonora para: Tratamento de Erros

O tratamento robusto de erros garante que falhas na síntese não resultem em custos indesejados. A API retorna códigos de status HTTP claros, permitindo que scripts de agências identifiquem problemas técnicos ou de entrada sem penalizar o saldo.

Para auditoria e debug, o sistema registra metadados essenciais de cada requisição. Esses logs permitem reconstruir o histórico de uso e verificar a exatidão das charges, mantendo a transparência exigida por contratos publicitários.

Falha na síntese

Caso a geração de áudio falhe (ex: texto inválido ou tempo limite excedido), o pedido é marcado como erro. O cliente recebe uma resposta JSON de erro, não áudio binário.

  • Erros de formato ou limite de caracteres retornam 400 ou 429.

Retorno de saldo

Se a síntese falhar, a cobrança é revertida integralmente. O saldo da conta é restaurado automaticamente, sem necessidade de solicitação manual. Isso evita desperdício de verba em testes de roteiros.

Logs de requisição

Metadados como timestamp, caracteres processados e status são mantidos para faturamento. Use esses dados para conciliação interna e auditoria de campanhas de rádio, sem armazenamento de áudio gerado.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Isso oferece controle preciso sobre o ritmo, essencial para sincronizar áudios de rádio ou vídeos com a edição visual.

Avatar da voz aria
ariafeminino
Avatar da voz nova
novafeminino
Avatar da voz luna
lunafeminino
Avatar da voz sage
sagefeminino
Avatar da voz felix
felixmasculino
Avatar da voz milo
milomasculino
Avatar da voz atlas
atlasmasculino
Avatar da voz orion
orionmasculino

23 idiomas

Qualquer voz fala qualquer um desses idiomas.

Fontes e leituras adicionais

  1. Wikipedia
  2. Creative Commons Attribution 4.0
  3. curl documentation
  4. openai-python on GitHub
  5. TRON developer hub: TRC-20
  6. LibriTTS-R corpus (OpenSLR 141)
  7. Tether (USDT)
  8. MDN: Web Speech API
  9. IETF RFC 7845: Ogg Opus
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. openai-node on GitHub
  12. LibriVox public-domain audiobooks

Mais neste site