Documentação técnica da API de síntese de fala

Por Equipe editorial VoicePublisher · Atualizado 2026-11-18

Esta documentação técnica descreve a integração da API de síntese de voz da VoicePublisher, projetada para publishers e plataformas de conteúdo. Você aprenderá a converter artigos em áudio de forma programática, utilizando o endpoint principal e os parâmetros essenciais para automatizar a leitura em voz alta nos seus sites.

O guia cobre autenticação via token, exemplos de requisição cURL, compatibilidade com os SDKs da OpenAI e estratégias para gerenciar textos longos e limites de taxa. Ideal para equipes de engenharia que buscam integrar acessibilidade e aumentar o tempo de permanência dos leitores com uma solução estável e transparente.

Documentação técnica da API de síntese de fala

Perguntas frequentes

Qual é o formato da resposta da API?

A API retorna o arquivo de áudio diretamente no corpo da resposta HTTP, no formato solicitado (mp3, wav, opus, flac ou pcm). Não há wrapper JSON para o áudio binário. O cabeçalho Content-Type indica o formato exato do arquivo recebido pelo cliente.

Como especificar o idioma no JSON?

Envie o código ISO do idioma no campo language do corpo da requisição JSON. Se omitido, o sistema tenta adivinhar pelo script do texto (padrão: inglês para latim). Para textos em latim fora do inglês, defina language explicitamente para evitar erros de pronúncia.

A API retorna metadados do áudio?

A resposta contém apenas o arquivo de áudio binário. Os metadados de uso, como tempo, caracteres processados e status, são armazenados para faturamento e podem ser consultados no painel da conta, mas não são retornados diretamente no payload da requisição de síntese.

Posso enviar texto com HTML?

O campo input aceita strings de texto. Como não há documentação sobre processamento semântico de tags HTML, o conteúdo é enviado diretamente ao motor de síntese. Recomendamos remover tags desnecessárias para evitar ruídos na fala. O texto enviado deve respeitar o limite de 4096 caracteres por solicitação.

Qual o código de erro para limite excedido?

O código HTTP é 429 Too Many Requests. O limite padrão é de 10 requisições por minuto por chave. Após o primeiro top-up, esse limite aumenta para 60 RPM. Ao exceder o limite, as requisições subsequentes retornarão 429 até que o intervalo de tempo seja resetado ou a chave seja renovada.

Como redefinir a chave API?

Acesse o painel em /get-api-key/. Ao gerar uma nova chave, a chave anterior é invalidada imediatamente. Não há período de transição; a chave antiga deixa de funcionar no exato momento em que a nova é emitida, garantindo segurança imediata para seus publishers.

O SDK Python funciona sem alterações?

Sim, utilize o SDK oficial da OpenAI. Apenas altere a propriedade base_url para https://api.playvc88.com/v1 e configure a chave Authorization: Bearer com sua chave da VoicePublisher. A forma do corpo da requisição é idêntica ao endpoint de fala da OpenAI.

Há suporte para SSML?

Não. A API não interpreta marcações SSML. O texto é enviado como string simples no campo input. O campo speed ajusta apenas a taxa de fala geral, não controla pausas ou ênfases específicas. Para pausas, divida o texto em múltiplas requisições. Não há suporte para dicionários de pronúncia ou tags de emoção.

Qual o tamanho máximo do payload JSON?

O limite crítico é o campo input, que aceita até 4096 caracteres por requisição. O payload JSON total depende do tamanho do texto e dos outros campos. Para textos maiores, divida manualmente em partes de 4096 caracteres e junte os arquivos de áudio resultantes.

A API retorna erro se o texto estiver vazio?

Sim, enviar um campo input vazio ou nulo resultará em erro de validação. O motor de síntese requer texto para gerar áudio. Certifique-se de que o campo contenha caracteres válidos antes de enviar a requisição POST para o endpoint de speech.

Posso usar variáveis de ambiente na chave?

Sim, você pode armazenar sua chave em variáveis de ambiente e passá-la no cabeçalho Authorization: Bearer. A API valida apenas o token fornecido. Não há restrição técnica contra o uso de variáveis de ambiente, que é a prática recomendada para segurança em produção.

O que significa o campo 'input'?

O campo input contém o texto bruto que será convertido em fala. Este é o único campo obrigatório para a síntese. O texto é processado literalmente, contando espaços e pontuação para o faturamento, e deve respeitar o limite de 4096 caracteres por chamada.

Como testar a velocidade de geração?

Envie uma requisição de teste via cURL ou SDK. O tempo de resposta varia: frases curtas levam alguns segundos; textos longos geram áudio em tempo real (aprox. 25 caracteres por segundo). Use o campo speed (0.25–4.0) para ajustar a velocidade da voz sintetizada.

Existe um endpoint para verificar saldo?

Não há endpoint REST dedicado para saldo. Consulte seu saldo, créditos de teste e caracteres restantes diretamente no painel em /get-api-key/. O histórico de uso e faturamento também está disponível na interface web, pois os metadados são mantidos para cobrança.

Primeira solicitação

curl

curl https://api.playvc88.com/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.playvc88.com/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.playvc88.com/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 e Chave API

Ilustração de onda sonora para: Autenticação e Chave API

A autenticação na VoicePublisher utiliza um único token Bearer válido por conta, emitido no painel /get-api-key/. Essa chave identifica sua conta e seu saldo disponível para o processamento das requisições, limitando o acesso aos endpoints da API a 60 requisições por minuto.

Para garantir a integridade das chamadas, inclua o token no cabeçalho Authorization de cada solicitação POST. A gestão da chave é centralizada: você pode revogá-la e gerar uma nova a qualquer momento diretamente no painel, sem necessidade de suporte externo.

Geração de chave no painel

Acesse a página /get-api-key/ após criar sua conta via Google ou e-mail. O painel exibe imediatamente a chave ativa, o saldo atual e a contagem de caracteres restantes. Não há necessidade de configurar múltiplos tokens; apenas uma chave está ativa por vez.

  • Chave única e ativa por conta
  • Visão imediata do saldo e métricas
  • Geração instantânea no dashboard

Cabeçalho Authorization Bearer

Inclua o cabeçalho HTTP padrão em todas as requisições ao endpoint /v1/audio/speech. O formato deve ser Bearer seguido do token alfanumérico gerado. Isso permite que o gateway identifique o assinante e deduza os caracteres consumidos do saldo disponível.

Revogação e nova chave

Se houver suspeita de uso não autorizado ou necessidade de rotação, gere uma nova chave no painel. A chave anterior torna-se inválida imediatamente, interrompendo qualquer requisição em andamento ou pendente que a utilize. Não há período de carência.

Endpoint Principal: /v1/audio/speech

Ilustração de onda sonora para: Endpoint Principal: /v1/audio/speech

O endpoint principal /v1/audio/speech aceita requisições POST em formato JSON. O corpo da mensagem deve conter o texto a ser sintetizado e as configurações desejadas, seguindo a estrutura padrão de síntese de fala.

O serviço processa o texto e retorna o arquivo de áudio gerado diretamente na resposta, permitindo integração automatizada em plataformas de notícias e conteúdo.

Método POST e formato JSON

Envie o payload JSON para POST https://api.playvc88.com/v1/audio/speech. O corpo da requisição deve incluir o campo input contendo o texto, o model ("tts-1" ou "tts-1-hd"), o voice desejado e o response_format (mp3, wav, opus, flac ou pcm).

  • Método: POST
  • Content-Type: application/json
  • Base URL: https://api.playvc88.com/v1

Campo input com texto máximo

O campo input aceita strings de até 4.096 caracteres. Espaços e pontuação contam como caracteres. Para textos longos, divida manualmente ou via script em partições e junte os arquivos resultantes.

  • Limite: 4.096 caracteres por requisição
  • Inclui espaços e pontuação
  • Texto em português ou qualquer idioma suportado

Resposta com arquivo de áudio

A resposta retorna o arquivo de áudio binário no formato solicitado (mp3, wav, opus, flac ou pcm). Em caso de falha na síntese, o saldo não é descontado. Se o áudio for gerado com sucesso, ele está pronto para ser baixado ou reproduzido.

  • Formatos: mp3, wav, opus, flac, pcm
  • Falhas são gratuitas
  • Áudio retornado diretamente na resposta
Endpoint Principal: /v1/audio/speech

Parâmetros de Requisição

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

Configure o corpo da requisição JSON enviando o texto a ser sintetizado. O campo input aceita até 4096 caracteres por chamada, incluindo espaços e pontuação. Defina o campo voice com o nome da preset desejada entre as 8 disponíveis e especifique a language se o texto não for em inglês, pois o padrão assume inglês para script latino.

Ajuste a velocidade de fala com o parâmetro speed, aceitando valores entre 0.25 e 4.0. O tempo de geração é aproximadamente real-time (25 caracteres por segundo). Para textos longos, divida o conteúdo em partes de 4096 caracteres e concatene os arquivos de áudio resultantes.

Modelo tts-1 e tts-1-hd

O campo model aceita apenas tts-1 ou tts-1-hd. Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço. A escolha entre eles não altera a qualidade percebida nem o custo por caractere, apenas o nome do recurso solicitado na API.

Voices predefinidas (8 opções)

Selecione uma das 8 vozes disponíveis. Todas falam os 23 idiomas suportados. A escolha define o timbre e o estilo da leitura, mas não há personalização de emoções ou clonagem de voz.

Femininas: aria (narradora clara), nova (dinâmica), luna (suave), sage (instrucional). Masculinas: felix (energética), milo (conversacional), atlas (neutra/notícias), orion (grave/documentário).

  • aria: narradora acolhedora e clara
  • nova: tom brilhante e dinâmico
  • luna: suave, ideal para storytelling
  • sage: calma, para conteúdo instrucional
  • felix: energética, adequada para promoções
  • milo: amigável e conversacional

Formatos de resposta aceitos

Defina o formato do arquivo de áudio retornado no campo response_format. As opções disponíveis são mp3, wav, opus, flac e pcm. O arquivo é retornado diretamente no corpo da resposta JSON.

Todos os arquivos gerados carregam uma marca d'água inaudível que identifica a síntese artificial. O formato escolhido deve ser compatível com o player de áudio da sua plataforma de notícias.

  • mp3
  • wav
  • opus
  • flac
  • pcm

Exemplo de Requisição cURL

Ilustração de onda sonora para: Exemplo de Requisição cURL

Use cURL para validar a integração da API de síntese de voz diretamente no terminal. O comando POST envia o texto para o endpoint principal, onde o serviço processa a requisição e retorna o arquivo de áudio gerado.

Este exemplo demonstra a estrutura mínima necessária para uma requisição bem-sucedida, permitindo que publishers verifiquem a entrega de áudio antes de implementar a lógica de integração em seus sistemas de publicação de conteúdo.

Comando básico de teste

Execute o comando abaixo para enviar um texto simples. Substitua SEU_TOKEN pela chave API obtida no painel e ajuste o texto no campo input. O modelo tts-1 é utilizado por padrão, oferecendo a opção de upgrade para tts-1-hd se necessário.

  • Método: POST
  • Endpoint: /v1/audio/speech
  • Formato: application/json

Substituição de variáveis

No comando, substitua SEU_TOKEN pelo valor da sua chave API ativa. O texto de entrada deve ser limitado a 4096 caracteres. Para textos maiores, realize múltiplas requisições sequenciais e junte os arquivos resultantes.

Verificação de resposta

Uma resposta bem-sucedida retorna o arquivo de áudio binário diretamente no corpo da resposta, no formato especificado (mp3, wav, opus, flac ou pcm). Verifique se o arquivo gerado é reproduzível e contém o áudio correspondente ao texto enviado.

Integração com SDK OpenAI

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

O SDK oficial da OpenAI funciona diretamente com a API VoicePublisher, exigindo apenas a reconfiguração do endpoint base. Isso permite aproveitar bibliotecas maduras e tipadas sem precisar escrever clientes HTTP personalizados para cada linguagem.

Utilize o mesmo código de integração, ajustando apenas a URL base para https://api.playvc88.com/v1. A estrutura JSON permanece idêntica ao endpoint de fala da OpenAI, garantindo compatibilidade imediata.

Alteração do base_url

Defina a variável de ambiente ou parâmetro base_url do cliente para https://api.playvc88.com/v1. Esta configuração direciona todas as requisições para nossa infraestrutura enquanto mantém o formato de payload padrão.

Essa abordagem permite usar a biblioteca oficial sem adaptações complexas na camada de transporte.

  • URL base: https://api.playvc88.com/v1
  • Formato de payload idêntico ao da OpenAI
  • Compatível com bibliotecas oficiais mais recentes

Uso de clientes oficiais

Instale o pacote openai via pip ou npm. Inicialize o cliente passando sua chave API no cabeçalho de autorização e a URL base reconfigurada.

O cliente gerencia automaticamente a serialização JSON e a transmissão dos dados de texto para síntese.

  • Suporte a Python, Node.js e Go
  • Gerenciamento automático de JSON
  • Autenticação via Bearer token

Compatibilidade de métodos

  • Mapeamento direto para POST
  • Parâmetros suportados: model, voice, input
  • Resposta binária completa
Integração com SDK OpenAI

Tratamento de Erros e Limites

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

A API impõe limites de velocidade baseados no estado da conta. Até o primeiro recarga, a taxa é de 10 requisições por minuto. Após o primeiro depósito, o limite aumenta para 60 requisições por minuto por chave. O excedente gera erro 429.

Código 429 para limites excedidos

Quando o limite de 10 req/min (pré-top-up) ou 60 req/min (pós-top-up) é atingido, o servidor retorna HTTP 429. Implemente lógica para respeitar esse código e evitar desperdício de caracteres na fila.

Tentativa em caso de falha

Requisições com falha de síntese são cobradas em zero. Se ocorrer erro temporário, reenvie a mesma solicitação. Como os pedidos são processados em fila, adicione um atraso exponencial para evitar colapso durante picos de demanda.

Contagem de requisições

O limite é de 60 req/min por chave após recarga, ou 10 req/min antes da primeira recarga. Não há cabeçalhos de controle de taxa na resposta; monitore o status HTTP 429 para ajustar a taxa de envio.

Listagem de Vozes e Modelos

Ilustração de onda sonora para: Listagem de Vozes e Modelos

O endpoint GET /v1/voices retorna a lista completa de vozes disponíveis, incluindo metadados como idioma suportado, formato e custo por caractere. Já o GET /v1/models lista os modelos de síntese ativa no sistema, permitindo que você selecione entre tts-1 ou tts-1-hd com base na necessidade de latência ou qualidade.

Esses endpoints são essenciais para validar a disponibilidade de recursos antes de iniciar o processamento em lote, garantindo que a infraestrutura de áudio esteja pronta para a integração.

Endpoint /v1/voices

Retorna um JSON com todos os vocais ativos e suas propriedades técnicas. Cada voz suporta as 23 línguas listadas nas especificações, permitindo que você escolha o parâmetro ideal sem precisar de múltiplos endpoints.

A resposta inclui informações sobre a linguagem padrão e a compatibilidade de formatos, facilitando a automação da escolha de voz para diferentes seções do site de notícias.

  • Retorna lista JSON de vozes ativas
  • Indica línguas suportadas por voz
  • Exibe formato e custo padrão
  • Permite seleção programática

Endpoint /v1/models

Liste os modelos de geração disponíveis, especificamente tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de síntese e possuem o mesmo custo por caractere, diferenciando-se apenas pela complexidade do processamento.

  • Modelos: tts-1 e tts-1-hd
  • Mesmo motor de síntese
  • Preço idêntico por caractere
  • Única diferença é a qualidade de áudio

Detalhes de cada voz

As 8 vozes são predefinidas e não podem ser clonadas ou customizadas. Elas são baseadas em gravações licenciadas do LibriTTS-R (CC BY 4.0) e de leituras de domínio público do LibriVox.

Cada vocal possui uma característica distinta, como 'warm' para Aria ou 'deep' para Orion, mas nenhuma é exclusiva de um idioma. Você deve definir o parâmetro 'language' explicitamente para textos em latim que não sejam inglês, para evitar a detecção automática incorreta.

  • 8 vozes predefinidas fixas
  • Baseadas em LibriVox e LibriTTS-R
  • Suporte a 23 idiomas
  • Sem clonagem ou customização
  • Requer definição explícita de 'language' para textos não-ingleses em latim
  • Marca d'água audível em todos os arquivos gerados
Listagem de Vozes e Modelos

Gerenciamento de Textos Longos

Ilustração de onda sonora para: Gerenciamento de Textos Longos

Para textos excedendo 4096 caracteres, a aplicação cliente deve dividir o conteúdo em segmentos menores e enviar requisições sequenciais. Cada requisição gera um arquivo de áudio independente, mantendo a estrutura narrativa original do artigo.

Os arquivos resultantes são concatenados localmente ou via serviço intermediário para formar a faixa de áudio final. Esse fluxo garante a entrega completa de artigos longos sem perda de dados ou cortes abruptos na narração.

Divisão em partes de 4096 chars

O limite de 4096 caracteres por requisição exige lógica de chunking no lado do cliente. Espaços e pontuação contam como caracteres. É necessário garantir que a divisão respeite os limites para evitar erros de entrada.

Juntar arquivos de áudio

Cada resposta da API contém um arquivo de áudio completo. Para textos longos, o cliente deve receber todos os fragmentos e uni-los na ordem correta. A latência varia conforme a fila de processamento, sendo o tempo médio de geração próximo ao tempo real.

Controle de velocidade

O parâmetro speed ajusta a velocidade de fala entre 0.25 e 4.0. Isso permite otimizar o tempo de execução para leituras rápidas ou permitir uma narração mais clara para acessibilidade. Ajustes finos ajudam a manter a naturalidade ao unir segmentos.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Os editores precisam adaptar suas estratégias para alcançar públicos cada vez mais exigentes e conectados globalmente.

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. openai-node on GitHub
  3. Python documentation
  4. W3C WAI: making audio and video accessible
  5. MDN: Web Speech API
  6. ISO 639 language codes
  7. Node.js documentation
  8. LibriTTS-R corpus (OpenSLR 141)
  9. openai-python on GitHub
  10. TRON developer hub: TRC-20
  11. IETF RFC 7845: Ogg Opus
  12. LibriTTS-R paper (arXiv 2305.18802)

Mais neste site