Integração da API de Texto para Voz: Guia Técnico Completo

Por Equipe editorial FalanteVoz · Atualizado 2026-11-19

Esta documentação técnica explica como integrar a API de texto para fala da FalanteVoz em sistemas de IVR e centrais de atendimento. Você aprenderá a autenticar, enviar requisições JSON e receber áudio pronto para uso, com controle total sobre velocidade e formato. Ideal para equipes de produto que buscam uma alternativa a provedores genéricos.

O guia abrange desde a obtenção da chave API até o tratamento de limites de taxa e erros comuns. Utilizamos o formato compatível com o SDK da OpenAI, facilitando a implementação em Python ou via cURL. Aqui, você encontrará todos os parâmetros necessários para gerar síntese de voz realista e eficiente em escala.

Integração da API de Texto para Voz: Guia Técnico Completo

Perguntas frequentes

Como obter a chave de API?

Acesse a página /get-api-key/ e registre-se com Google ou e-mail e senha. A interface exibe sua chave ativa, saldo e um exemplo de comando curl pronto para uso imediato na integração com a API de texto para fala.

Qual o formato padrão da resposta?

O endpoint POST /v1/audio/speech retorna o arquivo de áudio diretamente no corpo da resposta. Você pode escolher entre mp3, wav, opus, flac ou pcm. O conteúdo é entregue pronto para reprodução ou armazenamento imediato em seus sistemas.

Posso usar o SDK oficial do OpenAI?

Sim, basta alterar o base_url para https://api.3kauto.top/v1 e utilizar a chave da FalanteVoz. A forma do corpo da requisição é idêntica, permitindo que SDKs oficiais do OpenAI funcionem sem adaptações complexas na sua lógica de integração.

Qual a diferença entre tts-1 e tts-1-hd?

Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço. A escolha entre tts-1 e tts-1-hd não altera o custo por caractere.

Como especificar um idioma específico?

Defina o campo language com o código ISO desejado no corpo da requisição JSON. Se não informado, o sistema tenta adivinhar pelo script, mas textos em latinos fora do inglês devem ter o idioma explícito para evitar erros de pronúncia.

O que acontece se exceder o limite de requisições?

O limite é de 60 requisições por minuto por chave (10 antes do primeiro recarga). Exceder esse limite resulta em erro de rate limit até que o tempo de renovação do quota seja atingido, pausando temporariamente a geração de áudio.

Posso gerar áudio em formato PCM?

Sim, o campo response_format aceita pcm como uma das opções válidas. Isso é útil para integrações diretas com sistemas de IVR ou centrais de atendimento que exigem fluxo de áudio bruto não comprimido para processamento imediato ou transmissão.

A resposta inclui metadados do áudio?

A resposta HTTP contém apenas o arquivo de áudio binário. Metadados como tempo de processamento, caracteres usados e status são registrados para faturamento, mas não são incluídos no corpo da resposta da requisição de síntese enviada ao cliente.

Qual o tamanho máximo do texto por requisição?

O campo input aceita até 4096 caracteres por requisição. Para textos maiores, você deve dividi-los em partes dentro desse limite e unir os arquivos de áudio gerados manualmente para criar o arquivo final completo e contínuo.

O endpoint /v1/voices retorna preços?

Sim, a rota GET /v1/voices retorna informações sobre vozes, idiomas, formatos e preços. Isso permite que você consulte a estrutura de custos e as opções de áudio antes de iniciar a integração técnica com a API.

Posso revogar minha chave API?

Sim, você pode emitir uma nova chave a qualquer momento pela interface da conta. Ao fazer isso, a chave antiga é invalidada imediatamente, interrompendo qualquer uso contínuo dela, garantindo controle total sobre o acesso aos seus recursos.

A API suporta caracteres especiais em UTF-8?

O corpo da requisição JSON suporta caracteres Unicode, incluindo acentos e símbolos. Isso permite o processamento correto de textos nos idiomas suportados.

Qual o código de erro para falha de síntese?

Requisições com falha na síntese são processadas e o valor é devolvido integralmente. O código HTTP indicativo de erro será retornado, mas não há um código específico único mencionado para falha de síntese distinta de erros de requisição padrão.

Como integrar com JavaScript?

Utilize fetch ou axios para enviar um POST para https://api.3kauto.top/v1/audio/speech. Defina o header Authorization com Bearer sua-chave e o corpo JSON com model, input, voice e response_format. O SDK do OpenAI também funciona alterando o base_url.

Primeira solicitação

curl

curl https://api.3kauto.top/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.3kauto.top/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.3kauto.top/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

A autenticação é realizada mediante um token Bearer único, emitido ao criar sua conta na página /get-api-key/. Este token garante que cada requisição à API seja vinculada à sua conta e ao seu saldo atual.

Para integrar o serviço, inclua o cabeçalho Authorization: Bearer tts-... em todas as chamadas HTTP. A segurança é garantida pelo uso exclusivo desta chave ativa para cada conta.

Obtenção da chave API

Obtenção da chave API

Acesse /get-api-key/ e registre-se via Google ou e-mail. O painel exibe sua chave API ativa, saldo e histórico de uso.

Formato Bearer Token

Formato Bearer Token

Use o cabeçalho padrão HTTP Authorization: Bearer <sua_chave>. Bibliotecas OpenAI aceitam este formato automaticamente ao ajustar o base_url.

Revogação de chave

Ao gerar uma nova chave na interface, a anterior é invalidada instantaneamente. Isso permite revogar acesso sem necessidade de confirmação manual.

Endpoint Principal

Ilustração de onda sonora para: Endpoint Principal

A integração central da API ocorre via POST em /v1/audio/speech. O serviço processa texto e retorna o arquivo de áudio sintetizado diretamente no corpo da resposta JSON, facilitando a integração com sistemas de IVR e centrais de atendimento que necessitam de fluxos de áudio programáticos sem dependência de provedores genéricos.

POST /v1/audio/speech

O endpoint aceita requisições HTTP POST com corpo JSON. A sintaxe segue o padrão do endpoint de speech da OpenAI, permitindo reutilização de SDKs existentes. As requisições são processadas uma após a outra; sob carga, uma solicitação pode aguardar na fila.

Corpo da requisição JSON

O corpo deve conter os parâmetros essenciais para a síntese. O texto de entrada é limitado a 4096 caracteres por requisição. Para textos mais longos, a estratégia recomendada é dividir o conteúdo e unir os arquivos de áudio resultantes.

  • model: "tts-1" ou "tts-1-hd"
  • input: texto a ser sintetizado (máx. 4096 caracteres)
  • voice: identificador da voz selecionada
  • response_format: formato de saída (mp3, wav, opus, flac, pcm)
  • speed: velocidade entre 0.25 e 4.0
  • language: código ISO opcional

Parâmetros obrigatórios

Os campos model, input, voice e response_format são obrigatórios. O campo language é opcional; se não fornecido, o idioma é inferido pelo script, com default para inglês em textos latinos. Especificar o idioma explicitamente evita erros de síntese em textos latinos não ingleses.

Modelos e Voizes

Ilustração de onda sonora para: Modelos e Voizes

A API oferece dois modelos de síntese: "tts-1" e "tts-1-hd". Ambos utilizam o mesmo motor de geração e possuem preço idêntico, garantindo consistência na fatura independente da escolha técnica para seus fluxos de IVR.

O motor processa textos de até 4096 caracteres por requisição, retornando áudio pronto para integração em centrais de atendimento sem necessidade de processamento adicional no lado do cliente.

tts-1 vs tts-1-hd

Os modelos "tts-1" e "tts-1-hd" compartilham a mesma engine e o mesmo custo por caractere. A distinção reside apenas na configuração interna de qualidade, mas o preço permanece inalterado.

Lista de 8 vozes

O sistema disponibiliza oito vozes predefinidas, derivadas de gravações licenciadas (LibriTTS-R e LibriVox). Cada voz possui uma característica acústica distinta, permitindo a seleção precisa para diferentes contextos de atendimento ou narração automatizada.

  • Aria: feminina, tom de narradora clara e quente
  • Nova: feminina, tom brilhante e animado
  • Luna: feminina, tom suave e narrativo
  • Sage: feminina, tom calmo e instrucional
  • Felix: masculino, tom energético e promocional
  • Milo: masculino, tom amigável e conversacional
  • Atlas: masculino, tom neutro e jornalístico
  • Orion: masculino, tom profundo e documental

Suporte a idiomas

O motor suporta 23 idiomas específicos, incluindo português, inglês, espanhol e japonês. Qualquer voz pode falar qualquer um dos idiomas suportados, oferecendo flexibilidade para centralização de serviços globais sem múltiplas integrações.

Se o parâmetro language não for definido, o sistema tenta adivinhar o idioma pelo script (texto em latim assume inglês por padrão). Para textos em latim que não sejam inglês, defina explicitamente o código ISO para evitar erros de pronúncia.

  • Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish

Formatos de Saída

Ilustração de onda sonora para: Formatos de Saída

A API oferece cinco formatos de saída para atender às exigências técnicas de centrais de atendimento e IVRs. A escolha deve equilibrar a qualidade de áudio com a eficiência de banda, considerando que cada requisição gera um arquivo áudio completo.

O formato PCM é ideal para sistemas legados que exigem áudio bruto não comprimido. Já o OPUS e o MP3 otimizam a largura de banda, sendo recomendados para integrações modernas que priorizam a latência na transmissão de voz.

A qualidade varia conforme o codec selecionado, mas todos os arquivos entregues são sintéticos e contêm uma marca d'água inaudível. Não há compressão variável de qualidade; o formato define apenas a estrutura do arquivo recebido.

MP3, WAV, OPUS, FLAC, PCM

Selecione o formato via campo response_format. O MP3 e o OPUS oferecem a melhor relação entre tamanho e clareza para voz. O WAV e o FLAC preservam a qualidade sem perdas, úteis para gravações de alta fidelidade. O PCM retorna áudio bruto.

Cada formato tem implicações distintas no processamento. Enquanto o MP3 é universalmente compatível, o OPUS garante menor footprint de rede. O FLAC é um formato sem perdas.

  • mp3: compatível universalmente, compactação com perdas.
  • wav: áudio sem perdas, amplamente suportado.
  • opus: alta eficiência, ideal para VoIP.
  • flac: qualidade无损, arquivo maior que MP3.
  • pcm: áudio bruto, não comprimido.

Qualidade de áudio

A qualidade é determinada pelo modelo (tts-1 ou tts-1-hd) e não pelo formato de saída. Ambos os modelos utilizam a mesma engine de síntese, garantindo consistência na voz gerada.

O formato apenas encapsula o áudio resultante. Não há ajuste de bitrate ou taxa de amostragem configurável pelo usuário; a API define os parâmetros internos de codificação para cada codec disponível.

Tamanho do arquivo

O tamanho do arquivo varia conforme o texto e o formato escolhido. Em média, a geração ocorre em tempo real aproximado (25 caracteres por segundo).

Para textos longos, o áudio é dividido em partes de até 4096 caracteres. O cliente deve concatenar os arquivos recebidos para obter o áudio completo da mensagem.

O formato OPUS resulta em arquivos menores que WAV ou FLAC.

Exemplo cURL

Ilustração de onda sonora para: Exemplo cURL

O método mais direto para validar a integração é utilizar a ferramenta cURL no terminal. Este comando demonstra a sintaxe exata necessária para enviar um texto curto e receber o arquivo de áudio em formato MP3.

Comando de teste

Execute o comando abaixo substituindo <YOUR_API_KEY> pela sua chave ativa. O parâmetro input contém o texto a ser sintetizado, e voice define o timbre, como "nova".

  • curl -X POST "https://api.3kauto.top/v1/audio/speech" \ -H "Authorization: Bearer <YOUR_API_KEY>" \ -H "Content-Type: application/json" \ -d "{\"model\": \"tts-1\", \"input\": \"Olá, como posso ajudar?\", \"voice\": \"nova\", \"response_format\": \"mp3\"}"

Resposta esperada

O servidor retornará o arquivo de áudio binário diretamente no corpo da resposta. Não há estrutura JSON aninhada; o conteúdo é o fluxo de áudio pronto para ser salvo ou reproduzido.

Código de status

Um status HTTP 200 indica sucesso e entrega do arquivo. Caso a síntese falhe, o valor é estornado integralmente.

Exemplo cURL

SDK OpenAI

Ilustração de onda sonora para: SDK OpenAI

Utilize o SDK oficial da OpenAI, ajustando apenas o base_url para https://api.3kauto.top/v1. Isso permite reutilizar a mesma lógica de integração já conhecida, sem necessidade de bibliotecas proprietárias adicionais.

Configuração do base_url

Defina a variável de ambiente OPENAI_BASE_URL como https://api.3kauto.top/v1. O SDK dirige automaticamente as requisições para a API da FalanteVoz, mantendo a compatibilidade com a estrutura de payloads existente.

Compatibilidade de bibliotecas

Qualquer versão recente da biblioteca openai Python funciona. A comunicação ocorre via HTTP padrão, garantindo que clientes genéricos também se integrem sem adaptações complexas.

Exemplo em Python

Configure a chave Bearer com tts-... e invoque client.audio.speech.create(). O retorno é o arquivo de áudio pronto para ser salvo ou reproduzido.

  • Use response_format='mp3' para eficiência em redes móveis
  • Defina speed entre 0.25 e 4.0 para ajustar o tempo de resposta
  • Especifique voice conforme a persona desejada (ex: 'atlas' para notícias)

Limites e Erros

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

A API opera com um limite de 60 requisições por minuto por chave. Antes da primeira recarga, o limite é reduzido para 10 requisições por minuto. O processamento é sequencial; sob carga, as solicitações podem aguardar em uma fila, o que impacta a latência percebida.

60 requisições por minuto

Cada chave de API permite até 60 chamadas por minuto. Durante o período de avaliação gratuita, antes do primeiro depósito, o limite é mais restrito, permitindo apenas 10 requisições por minuto. Esse controle garante a estabilidade do serviço para integrações em tempo real em centrais de atendimento.

Erro 429 Too Many Requests

Quando o limite é excedido, a API retorna o código HTTP 429. Isso indica que você deve pausar o envio de novas requisições até que o intervalo de um minuto se renove. Recomenda-se implementar lógica de *backoff* exponencial nos clientes para evitar picos de tráfego simultâneos.

  • Código HTTP: 429
  • Mensagem: "Too Many Requests"
  • Ação recomendada: aguardar e retentar com intervalo crescente

Tratamento de falhas

Se a síntese falhar devido a problemas internos, o valor é estornado integralmente. Para garantir a entrega de textos longos, divida o conteúdo em partes de até 4096 caracteres e una os arquivos de áudio gerados. Monitore os códigos de status para distinguir entre erros de requisição e limites excedidos.

  • Erros de síntese têm reembolso automático
  • Texto máximo: 4096 caracteres por requisição
  • Implemente lógica de retry para 429

Outros Endpoints

Ilustração de onda sonora para: Outros Endpoints

Além do endpoint principal de síntese, a API oferece endpoints dedicados para gestão de metadados, permitindo que equipes de produto antecipem custos e escolham vozes adequadas ao contexto de IVR antes de enviar texto.

Esses endpoints retornam informações estruturadas sobre os modelos disponíveis e as configurações de cada voz, facilitando a integração automatizada em painéis administrativos ou sistemas de atendimento.

O uso correto desses dados evita erros de formato e otimiza o consumo de caracteres ao selecionar a combinação ideal de velocidade e qualidade.

GET /v1/voices

Retorna a lista completa das 8 vozes disponíveis, incluindo seus identificadores, gêneros e idiomas suportados. Cada voz pode falar qualquer um dos 23 idiomas listados, o que simplifica a lógica de seleção para centrais de atendimento multilíngues.

A resposta inclui informações sobre vozes, idiomas, formatos e preços.

  • ID da voz (ex: aria, nova, atlas)
  • Gênero e tom (ex: narrador, noticioso)
  • Idiomas suportados (23 opções)
  • Formato de áudio padrão

GET /v1/models

Retorna os modelos de síntese disponíveis: tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de IA e têm o mesmo preço, diferenciando-se apenas na qualidade de saída de áudio.

Esses modelos são compatíveis com todos os formatos de saída (mp3, wav, opus, flac, pcm) e velocidades entre 0.25x e 4.0x.

  • tts-1: Modelo padrão
  • tts-1-hd: Modelo de alta definição
  • Mesmo preço por caractere
  • Mesma velocidade de processamento

Metadados de voz

Cada voz possui características técnicas específicas, como faixa de velocidade recomendada e idioma de origem. Esses metadados são atualizados em tempo real e refletidos nas respostas dos endpoints.

A utilização correta dos metadados garante que a síntese seja realizada com a qualidade esperada, evitando erros de formatação ou incompatibilidade de idioma.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Não oferecemos suporte por telefone, chat ao vivo ou número de contato direto.

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. TRON developer hub: TRC-20
  4. Python documentation
  5. Tether (USDT)
  6. LibriTTS-R corpus (OpenSLR 141)
  7. LibriVox public-domain audiobooks
  8. Node.js documentation
  9. FFmpeg documentation
  10. ISO 639 language codes
  11. openai-python on GitHub
  12. MDN: Web Speech API

Mais neste site