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.mp3Python (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 | |
|---|---|
aria | feminino |
nova | feminino |
luna | feminino |
sage | feminino |
felix | masculino |
milo | masculino |
atlas | masculino |
orion | masculino |
| language | |
|---|---|
ar | العربية |
zh | 中文 |
da | Dansk |
nl | Nederlands |
en | English |
fi | Suomi |
fr | Français |
de | Deutsch |
el | Ελληνικά |
he | עברית |
hi | हिन्दी |
it | Italiano |
ja | 日本語 |
ko | 한국어 |
ms | Bahasa Melayu |
no | Norsk |
pl | Polski |
pt | Português |
ru | Русский |
es | Español |
sw | Kiswahili |
sv | Svenska |
tr | Türkçe |
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
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

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
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
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

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
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

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.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
