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

Por Equipe editorial VozSintonia · Atualizado 2026-11-19

Esta documentação técnica explica como integrar a API VozSintonia em assistentes virtuais e chatbots utilizando o SDK da OpenAI (compatível por padrão de corpo JSON). Você aprenderá a configurar a chave Bearer, enviar texto para síntese e receber arquivos de áudio em formatos como MP3 ou WAV, mantendo a compatibilidade total com o formato de corpo JSON padrão.

O guia cobre desde a autenticação e os parâmetros de entrada até o tratamento de erros e limites de taxa. Ideal para equipes de desenvolvimento que precisam de controle preciso sobre velocidade, idioma e formato, esta página apresenta exemplos práticos, como comandos curl e ajustes de latência, para uma implementação direta em seus fluxos de atendimento.

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

Perguntas frequentes

Qual o formato de corpo da requisição?

O corpo da requisição deve ser enviado como JSON. Os campos aceitos são model, input, voice, response_format, speed e language. A estrutura é idêntica ao endpoint de fala da OpenAI, facilitando a integração imediata com seus sistemas existentes.

Posso usar o SDK oficial da OpenAI?

Sim. Como o formato de requisição é o mesmo, você pode usar os SDKs da OpenAI. Basta alterar o base_url para https://api.0657.info/v1 e utilizar sua chave de API própria. A: Sim. Como o formato de requisição é o mesmo, você pode usar os SDKs da OpenAI.

Qual o limite máximo de caracteres por solicitação?

Cada solicitação aceita até 4096 caracteres. Se o texto for maior, você deve dividi-lo em partes menores e juntar os arquivos de áudio resultantes. Essa abordagem garante que cada chamada seja processada eficientemente, mantendo a qualidade do áudio e respeitando os limites técnicos da API.

A velocidade afeta o custo da API?

Não. O custo é calculado exclusivamente com base no número de caracteres do texto de entrada, independentemente da velocidade ajustada. A velocidade (entre 0.25 e 4.0) altera apenas a duração do áudio gerado, mas não impacta a contagem de caracteres nem o valor cobrado na sua conta.

O que é o modelo tts-1-hd?

O modelo tts-1-hd é uma das duas opções de motor de síntese disponíveis, oferecendo alta qualidade de áudio. Ele possui o mesmo preço do modelo padrão tts-1, permitindo que você escolha a qualidade desejada sem variação de custo. Ambos utilizam as mesmas vozes e configurações disponíveis.

Posso enviar texto em vários idiomas na mesma solicitação?

Sim, você pode enviar texto em vários idiomas. A API detecta automaticamente o idioma com base no script, mas você pode forçar um idioma específico usando o campo language. Se não for definido, o texto em latim é assumido como inglês. O contexto muda naturalmente entre idiomas.

Como detectar erros de formatação JSON?

A API retorna códigos de status HTTP padrão para erros de sintaxe ou campos ausentes. Verifique o código de status na resposta (como 400 para erro de entrada). O corpo da resposta conterá uma mensagem detalhando o campo com problema, permitindo correção imediata na estrutura JSON enviada.

A API retorna metadados do áudio?

A resposta contém o arquivo de áudio diretamente, sem metadados extensos sobre o conteúdo gerado. Os metadados de uso, como tempo, caracteres e status, são mantidos para faturamento e visíveis no painel da conta. Não há informação embutida no arquivo de áudio sobre a voz ou modelo utilizado.

Qual o tempo médio de resposta?

O tempo varia conforme o tamanho do texto e a carga do sistema. Textos longos são gerados em tempo real aproximado, cerca de 25 caracteres por segundo. Frases curtas levam alguns segundos. Em momentos de alta demanda, as requisições podem aguardar na fila antes do processamento.

Posso usar HTTPS sem certificado customizado?

Sim. A API utiliza HTTPS padrão. Não é necessário configurar certificados customizados ou validar CNs específicos além do domínio da API. A conexão segura é estabelecida automaticamente pelas bibliotecas HTTP padrão.

A chave API é sensível?

Sim. A chave deve ser mantida em sigilo, pois concede acesso à sua conta e saldo. Cada conta possui uma chave ativa por vez. Se você emitir uma nova chave, a anterior é invalidada imediatamente. Proteja sua chave como faria com uma senha de acesso principal.

Há limite de tamanho do arquivo de áudio retornado?

Não há um limite rígido de tamanho de arquivo especificado, mas o tamanho depende diretamente da duração do texto e da velocidade. Como cada requisição é limitada a 4096 caracteres, o arquivo resultante terá tamanho proporcional a essa duração máxima, gerenciável pela divisão de textos longos.

Posso usar o mesmo endpoint para diferentes vozes?

Sim. O endpoint POST /v1/audio/speech é único para todas as vozes. Você seleciona a voz desejada (como aria, nova, ou atlas) passando o nome dela no campo voice da requisição JSON. Isso permite alternar entre vozes femininas e masculinas sem alterar a URL ou a estrutura da chamada.

O que acontece se exceder os 60 requests por minuto?

Se exceder 60 solicitações por minuto, as requisições adicionais receberão um erro de limite de taxa. Você deve aguardar até que o contador de tempo recomece ou reduzir a frequência de chamadas. Esse limite é aplicado por chave de API e garante a estabilidade do serviço para todos os usuários.

Primeira solicitação

curl

curl https://api.0657.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.0657.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.0657.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 e chave API

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

A autenticação na API VozSintonia utiliza o padrão Bearer Token. A chave API, iniciada por "tts-", deve ser enviada no cabeçalho Authorization de cada requisição HTTP. Ela é exclusiva para a conta criada no site e garante o acesso aos endpoints de síntese e configuração.

Formato da chave Bearer

Formato da chave Bearer

Inclua o cabeçalho Authorization: Bearer tts-... em todas as chamadas. O formato segue o padrão OAuth 2.0, compatível com bibliotecas HTTP modernas e SDKs de terceiros.

Emissão de nova chave

Emissão de nova chave

Acesse o painel /get-api-key/ para visualizar sua chave ativa. Você pode gerar uma nova chave a qualquer momento diretamente na interface da conta.

Revogação automática

A geração de uma nova chave invalida imediatamente a anterior. Não há período de carência; a chave antiga deixa de funcionar no exato momento da criação da nova, garantindo segurança imediata sem necessidade de confirmação manual.

Endpoint principal de síntese

Ilustração de onda sonora para: Endpoint principal de síntese

A síntese de voz é realizada enviando texto para o endpoint POST /v1/audio/speech. O serviço retorna o arquivo de áudio pronto para uso, sem necessidade de streaming ou conexões WebSocket. Esta abordagem simplifica a integração em pipelines de atendimento automatizado.

O formato de corpo JSON segue o padrão usado pelo endpoint de speech da OpenAI, permitindo reutilizar bibliotecas existentes. Basta ajustar o base_url para https://api.0657.info/v1. Isso facilita a migração e a manutenção de código em equipes de desenvolvimento.

A API processa requisições sequencialmente, garantindo que cada solicitação seja executada individualmente. Isso é ideal para chatbots que não exigem latência de tempo real estrita, focando na precisão da geração de áudio.

Método POST /v1/audio/speech

Utilize o método POST para enviar texto e receber áudio. O endpoint aceita requisições JSON padrão, compatível com a maioria das linguagens de programação.

A resposta contém o arquivo de áudio no formato solicitado, pronto para ser reproduzido ou armazenado temporariamente em seus servidores.

  • URL base: https://api.0657.info/v1
  • Método: POST
  • Formato de resposta: arquivo de áudio binário

Corpo JSON padrão

O corpo da requisição deve incluir o texto a ser sintetizado e a voz desejada. O formato é idêntico ao usado na API de speech da OpenAI.

Isso permite o uso do SDK da OpenAI, alterando apenas a URL base. Campos como model e voice são especificados no corpo JSON.

A API não suporta SSML ou marcações de emoção, mantendo a estrutura simples e previsível para automações.

Campos obrigatórios e opcionais

Os campos model, input e voice são essenciais para a síntese. O model define a qualidade (tts-1 ou tts-1-hd), o input contém o texto e o voice seleciona o timbre.

Parâmetros como response_format, speed e language são opcionais. A linguagem é inferida automaticamente, mas deve ser definida para textos em latim não ingleses.

Cada requisição processa até 4096 caracteres. Textos maiores devem ser divididos manualmente antes do envio.

Parâmetros de entrada

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

Os parámetros de entrada definem como o texto será convertido em áudio. A configuração básica inclui o modelo, o texto de entrada, a voz, a velocidade e o idioma.

Esta seção detalha os campos obrigatórios e opcionais para garantir a síntese correta nas suas aplicações de assistente virtual.

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 por caractere. A escolha entre eles é baseada na qualidade de áudio desejada, sem diferença de custo ou performance de latência.

Input texto até 4096 caracteres

  • Limite: 4096 caracteres por chamada.
  • Custo: $0,01 por 1.000 caracteres (espaços incluídos).

Voice, speed e language

O campo voice recebe uma das 8 presets disponíveis (ex: aria, nova, felix). O campo speed ajusta a velocidade entre 0.25 e 4.0. O language é opcional; se não fornecido, o idioma é detectado pelo script, com padrão inglês para texto em latim.

  • Voizes: 8 presets fixos (ex: aria, milo).
  • Velocidade: 0.25 a 4.0.
  • Idioma: detectado automaticamente ou definido via ISO code.

Formatos de áudio suportados

Ilustração de onda sonora para: Formatos de áudio suportados

A API aceita MP3, WAV, OPUS, FLAC e PCM para atender diferentes necessidades de infraestrutura. A escolha do formato impacta diretamente a latência e o tamanho do arquivo, permitindo equilibrar velocidade de entrega e qualidade de áudio conforme o requisito do sistema.

Para assistentes virtuais, formatos leves como OPUS reduzem o tempo de resposta, enquanto WAV ou FLAC são ideais para gravações de alta fidelidade. O PCM é útil para integrações que exigem áudio bruto não comprimido.

MP3, WAV, OPUS, FLAC, PCM

Todos os formatos listados são suportados nativamente no campo response_format da requisição. A API gera o arquivo correspondente imediatamente após a síntese bem-sucedida.

Escolha baseada em latência

Se o seu chatbot requer resposta imediata, utilize OPUS ou MP3. Eles oferecem melhor relação tamanho/qualidade para transferência via HTTP padrão, minimizando o tempo de espera do usuário final.

Qualidade vs. tamanho

Escolha WAV ou FLAC se precisar de áudio sem perda de compressão para análise posterior ou gravação em banco de dados. O PCM fornece dados brutos, ideal para processamento de sinal contínuo sem decodificação intermediária.

Limites de taxa e fila

Ilustração de onda sonora para: Limites de taxa e fila

Os limites de taxa garantem estabilidade para equipes de desenvolvimento que integram voz a chatbots. O sistema processa requisições em fila sequencial, priorizando a integridade do áudio gerado.

Compreender esses limites ajuda a ajustar a arquitetura de chamadas, evitando throttling desnecessário durante picos de uso em assistentes virtuais.

60 requisições por minuto

Cada chave API permite até 60 requisições por minuto. Esse limite é suficiente para a maioria dos fluxos de atendimento padrão e garante que o serviço permaneça responsivo mesmo sob carga moderada.

10 requisições iniciais

Contas recém-criadas começam com uma cota reduzida de 10 requisições por minuto. Isso permite testar a integração sem saturar os recursos imediatamente. O limite é elevado automaticamente após o primeiro top-up.

Processamento sequencial

As requisições são processadas uma após a outra. Para textos longos, o áudio é gerado em partes e unido posteriormente. Em momentos de alta demanda, uma requisição pode aguardar na fila antes do início da síntese.

Limites de taxa e fila

Exemplo com curl

Ilustração de onda sonora para: Exemplo com curl

O comando abaixo demonstra a chamada direta à API para gerar áudio de um assistente virtual. Substitua a chave de autenticação e o texto de exemplo antes de executar.

A resposta retorna o arquivo de áudio binário diretamente no corpo da resposta, permitindo o processamento imediato sem necessidade de download adicional.

Comando completo

Execute a solicitação POST para o endpoint de síntese. O corpo JSON deve conter o modelo, o texto a ser falado e o identificador da voz desejada.

Certifique-se de que o texto não exceda 4096 caracteres e que a chave Bearer esteja correta no cabeçalho de autorização.

  • Endpoint: POST https://api.0657.info/v1/audio/speech
  • Formato: application/json
  • Autenticação: Bearer tts-sua-chave-aqui

Resposta esperada

O servidor retornará o arquivo de áudio no formato solicitado (mp3, wav, opus, flac ou pcm). O conteúdo da resposta é binário e pronto para ser reproduzido ou armazenado.

A latência depende do comprimento do texto e da fila de processamento, sendo geralmente próxima do tempo real para textos longos.

Tratamento de erro

Se a síntese falhar, o crédito será devolvido integralmente. Verifique os códigos de status HTTP para identificar problemas de autenticação ou limites de taxa excedidos.

Para erros de corpo da requisição, a resposta incluirá uma mensagem clara indicando o campo inválido ou a restrição violada.

Integração com OpenAI SDK

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

A API de síntese de voz é compatível com os SDKs da OpenAI. Para utilizá-los, basta alterar a propriedade base_url para https://api.0657.info/v1 e configurar a chave API no cabeçalho de autenticação.

Essa configuração permite que você utilize as mesmas bibliotecas que já conhece, mantendo a estrutura de código existente sem necessidade de adaptações complexas.

Configuração do base_url

Defina base_url como https://api.0657.info/v1. Utilize a mesma chave tts-... gerada em sua conta.

O SDK enviará automaticamente o cabeçalho Authorization: Bearer para cada requisição.

  • Base URL: https://api.0657.info/v1
  • Autenticação: Bearer <sua-chave-api>

Uso do mesmo formato de corpo

O corpo JSON segue o padrão da endpoint de fala da OpenAI. Campos como model, input, voice e response_format funcionam da mesma forma.

A velocidade (speed) aceita valores de 0.25 a 4.0, permitindo ajustes precisos para seus fluxos de chatbot.

Compatibilidade total

As bibliotecas da OpenAI funcionam diretamente com nossa API. Não é necessário instalar pacotes adicionais ou criar wrappers customizados.

A estrutura de resposta também é idêntica, facilitando o tratamento do arquivo de áudio gerado em suas aplicações.

  • SDKs da OpenAI compatíveis
  • Estrutura de resposta idêntica

Tratamento de erros

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

A API retorna códigos HTTP padrão para indicar o status de cada requisição. Código 200 indica sucesso, enquanto 400 sinaliza parâmetros inválidos e 429 indica limite de taxa excedido. Cada resposta contém detalhes específicos para facilitar o diagnóstico rápido.

Códigos de status HTTP

Use os códigos padrão HTTP para controle de fluxo. 200 OK para sucesso, 400 Bad Request para erros de validação, 401 Unauthorized para chave inválida e 429 Too Many Requests quando o limite de 60 rpm for atingido.

  • 200: Sucesso, áudio retornado.
  • 400: Parâmetros inválidos (ex: texto > 4096 chars).
  • 401: Chave de API ausente ou inválida.
  • 429: Limite de taxa excedido (rate limit).

Mensagens de erro claras

Cada erro de validação inclui uma mensagem descritiva no corpo JSON da resposta. Isso permite que você identifique exatamente qual campo falhou (modelo, voz ou formato) sem precisar adivinhar.

Retorno de crédito em falhas

Se a síntese falhar, o crédito correspondente é devolvido integralmente à sua conta. Não há cobrança por tentativas que resultem em erro, garantindo que você pague apenas por áudio gerado com sucesso.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase.

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. MDN: Web Speech API
  3. Tether (USDT)
  4. FFmpeg documentation
  5. Creative Commons Attribution 4.0
  6. curl documentation
  7. ISO 639 language codes
  8. TRON developer hub: TRC-20
  9. Node.js documentation
  10. LibriTTS-R corpus (OpenSLR 141)
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. openai-node on GitHub

Mais neste site