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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
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
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.

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
speedentre 0.25 e 4.0 para ajustar o tempo de resposta - Especifique
voiceconforme a persona desejada (ex: 'atlas' para notícias)
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
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.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
