Perguntas frequentes
Qual a estrutura do JSON de entrada?
O corpo da requisição POST deve conter os campos obrigatórios model ("tts-1" ou "tts-1-hd"), input (texto até 4096 caracteres) e voice (um dos 8 presets). Opcionalmente, você pode incluir response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) e language (código ISO).
Posso usar o SDK oficial da OpenAI?
Sim. A API segue a mesma estrutura de endpoint da OpenAI. Você deve alterar o base_url para https://api.778bet.info/v1 e utilizar a chave da ClarezaVoz. Isso permite usar os SDKs oficiais da OpenAI diretamente, sem necessidade de adaptações complexas no código.
Como alterar a velocidade da voz?
Use o parâmetro speed no corpo da requisição JSON. O valor aceito varia de 0.25 a 4.0, permitindo acelerar ou desacelerar a fala conforme necessário. O padrão é 1.0. Note que textos longos são processados sequencialmente, então a velocidade afeta o tempo total de geração.
Qual o tamanho máximo do texto?
O limite é de 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos maiores, você deve dividi-los em partes de até esse limite e juntar os arquivos de áudio resultantes. Cada caractere conta para a cobrança, que é de $0.01 por 1.000 caracteres.
As vozes falam todos os idiomas?
As 8 vozes suportam 23 idiomas específicos: Árabe, Chinês, Dinamarquês, Holandês, Inglês, Finlandês, Francês, Alemão, Grego, Hebraico, Hindi, Italiano, Japonês, Coreano, Malaio, Norueguês, Polonês, Português, Russo, Espanhol, Suaíli, Sueco e Turco. Qualquer voz pode falar qualquer um desses idiomas. Idiomas como Vietnamita ou Tailandês não são suportados.
O que é o parâmetro language?
É um código ISO opcional que define o idioma da fala. Se não definido, o sistema tenta adivinhar pelo script (texto em latim assume Inglês). Para textos em outros idiomas com alfabeto latino, defina language explicitamente para evitar erros de pronúncia ou detecção incorreta.
Como identificar erros na requisição?
A API retorna códigos de status HTTP padrão. Se a síntese falhar, o erro é retornado sem cobrança. Você deve verificar o código de status e a mensagem de erro no corpo da resposta JSON. Solicitações falhas têm o valor devolvido integralmente.
Posso emitir uma nova chave se perder a antiga?
Sim. Sua conta permite apenas uma chave ativa por vez. Ao emitir uma nova chave, a anterior é invalidada imediatamente. Isso garante segurança, pois você não precisa gerenciar múltiplas chaves ativas simultaneamente, apenas a chave corrente usada nas requisições.
Primeira solicitação
curl
curl https://api.778bet.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.778bet.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.778bet.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 | |
|---|---|
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
Para utilizar a API de síntese de voz da ClarezaVoz, é necessário gerar uma chave Bearer exclusiva. O acesso é obtido diretamente na página /get-api-key/, onde o sistema exibe a chave ativa, o saldo disponível e as métricas de uso em tempo real.
Essa chave deve ser incluída no cabeçalho Authorization de todas as requisições. Cada conta mantém apenas uma chave ativa por vez, garantindo controle preciso sobre os endpoints consumidos.
Obtenção da chave Bearer
A autenticação é realizada enviando o cabeçalho Authorization: Bearer tts-<sua-chave> nas requisições POST. A chave é visível imediatamente após o login via Google ou criação de conta por e-mail na seção de configurações da API.
Não há necessidade de configurar tokens de acesso complexos ou rotas de OAuth adicionais. A chave funciona como um identificador único e direto para sua conta e saldo.
- Chave gerada na página /get-api-key/
- Cabeçalho: Authorization: Bearer tts-...
Emissão de nova chave
Caso a chave seja comprometida ou você precise de um ponto de reset, é possível emitir uma nova chave a qualquer momento diretamente no painel.
A ação é imediata e não requer aprovação externa ou tempo de espera para validação bancária.
Invalidação imediata da chave antiga
Assim que uma nova chave é emitida, a chave anterior torna-se inválida instantaneamente. Qualquer requisição feita com o token antigo retornará erro de autenticação.
Isso elimina a janela de vulnerabilidade comum em sistemas que mantêm chaves legadas ativas por alguns minutos ou horas.
Endpoint Principal
O núcleo da ClarezaVoz reside no endpoint POST https://api.778bet.info/v1/audio/speech. Este é o único ponto de entrada necessário para transformar texto em áudio, seguindo o padrão de requisição do OpenAI para facilitar a integração em plataformas de e-commerce e SaaS.
O corpo da requisição deve ser enviado como JSON, contendo o texto a ser sintetizado e as configurações de áudio. A API processa a entrada e retorna o arquivo de áudio gerado diretamente na resposta, sem necessidade de armazenamento intermediário ou polling.
POST /v1/audio/speech
Envie requisições HTTP POST para https://api.778bet.info/v1/audio/speech. Este endpoint aceita texto bruto e retorna o arquivo de áudio sintetizado correspondente, pronto para ser integrado em sua aplicação.
O formato da requisição é idêntico ao do OpenAI, permitindo que você utilize SDKs oficiais ou chamadas HTTP diretas apenas ajustando a URL base.
Formato JSON do corpo
O corpo da requisição deve ser serializado como JSON. Os campos obrigatórios incluem model ("tts-1" ou "tts-1-hd"), input (o texto, limitado a 4096 caracteres) e voice (identificador da voz escolhida).
Campos opcionais como response_format, speed e language permitem controle preciso sobre o resultado final, garantindo que o áudio se adapte às necessidades técnicas do seu projeto.
Recebimento do arquivo de áudio
A resposta contém o arquivo de áudio binário no formato solicitado. Não há armazenamento persistente dos arquivos gerados; eles são entregues diretamente na resposta HTTP para uso imediato.
Se a síntese falhar, o valor pago é devolvido integralmente, garantindo que você não seja cobrado por áudio que não foi entregue.
Parâmetros de Requisição
A integração com a API exige o envio de um corpo JSON contendo os parâmetros essenciais para a síntese. O formato é compatível com o padrão OpenAI, facilitando a adaptação para plataformas de e-commerce e SaaS que já utilizam SDKs existentes.
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 preço idêntico, permitindo alternância sem impacto financeiro ou na qualidade percebida do áudio gerado.
Texto de entrada (input)
O parâmetro input recebe a string de texto a ser convertida. O limite técnico é de 4096 caracteres por requisição, incluindo espaços e pontuação. Textos longos devem ser divididos manualmente em partes menores e unidos posteriormente para garantir a integridade do áudio.
Configuração de voz e idioma
Defina voice com um dos 8 IDs disponíveis (ex: "aria", "nova"). O idioma pode ser especificado via language (código ISO). Se omitido, o sistema tenta adivinhar pelo script, mas textos em latim são padronizados para inglês por padrão, exigindo definição explícita para outras línguas.
Formatação e Velocidade
A API retorna áudio nos formatos mp3, wav, opus, flac ou pcm. O opus é eficiente para web e mobile, enquanto o pcm oferece dados brutos não comprimidos. A escolha depende da necessidade de compatibilidade ou tamanho de arquivo.
A velocidade de reprodução varia de 0.25 a 4.0, permitindo ajustar o ritmo da fala para diferentes contextos de uso.
Formatos: mp3, wav, opus, flac, pcm
O formato opus é eficiente para web e mobile, enquanto o pcm oferece dados brutos não comprimidos.
Velocidade de 0.25 a 4.0
Ajuste a velocidade de reprodução entre 0.25 e 4.0 para adaptar o ritmo da fala ao contexto da sua aplicação.
Detecção automática de idioma
Se o campo language não for definido, o sistema tenta adivinhar o idioma com base no script do texto. Textos em latim padrão para inglês. Para outros idiomas em latim, defina o language explicitamente.
Exemplo com cURL
A interação direta via linha de comando permite validar rapidamente a integração antes da implementação em produção. O comando cURL envia o texto e os metadados necessários para o endpoint de síntese.
Este exemplo demonstra a estrutura mínima necessária para gerar um arquivo de áudio MP3, utilizando os parâmetros padrão de modelo e voz.
Comando básico de POST
O corpo da requisição deve ser enviado como JSON, contendo o campo input com o texto a ser convertido. O modelo tts-1 é suficiente para a maioria dos casos de uso em e-commerce.
Inclusão da chave de autenticação
A chave gerada na página /get-api-key/ deve ser passada no cabeçalho Authorization. Sem este token, a API retornará erro de acesso.
Salvamento do arquivo de resposta
O comando redireciona o corpo binário da resposta para um arquivo local. Isso permite testar a qualidade do áudio gerado imediatamente no terminal.

Integração com SDK OpenAI
A API de síntese de voz utiliza o mesmo formato de requisição da API de áudio da OpenAI, permitindo que desenvolvedores integrem a ClarezaVoz em projetos existentes com mínima alteração de código. Basta ajustar a URL base e a chave de autenticação para redirecionar as chamadas para nossos servidores.
Essa compatibilidade elimina a necessidade de aprender uma nova estrutura de payloads. Você pode utilizar as bibliotecas oficiais da OpenAI, ajustando apenas o endpoint, o que acelera a implementação em plataformas de comércio eletrônico e aplicações SaaS que já dependem dessas SDKs para outras funções.
Alteração do base_url
Para utilizar a ClarezaVoz com o SDK OpenAI, configure o parâmetro base_url para https://api.778bet.info/v1. Isso redireciona todas as requisições de síntese de áudio diretamente para a nossa infraestrutura, mantendo a estrutura padrão de endpoints.
Essa configuração garante que as chamadas para o endpoint /v1/audio/speech sejam processadas pelos nossos servidores de TTS, sem necessidade de modificar a lógica de envio de dados ou a estrutura do corpo da requisição.
Uso da classe oficial de cliente
Instantiate a classe OpenAI passando a chave API via api_key. Utilize a mesma chave de autenticação obtida em seu painel de controle na página /get-api-key/. O SDK cuida da serialização JSON e do envio da requisição POST.
O objeto de cliente gerado utiliza a URL base definida anteriormente. Ao chamar o método audio.speech.create(), o SDK envia automaticamente os dados para o endpoint correto, autenticando cada solicitação com sua chave Bearer.
Compatibilidade com request shape
O corpo da requisição segue exatamente o padrão da API de áudio da OpenAI, incluindo os campos model, input, voice e response_format. Essa uniformidade permite que códigos escritos para serviços concorrentes sejam adaptados rapidamente.
Não é necessário mapear campos personalizados ou converter estruturas de dados. O SDK OpenAI já formata corretamente o JSON enviado para https://api.778bet.info/v1, garantindo que parâmetros como speed e language sejam interpretados sem erros de sintaxe.
Essa compatibilidade facilita a migração ou o uso paralelo de múltiplos provedores TTS em uma mesma aplicação, pois a assinatura dos métodos permanece idêntica.
Limites e Erros
A API opera com um limite de 60 requisições por minuto por chave. Antes da primeira recarga, esse limite é reduzido para 10 requisições por minuto.
Solicitações malformadas ou com erros de processamento são gratuitas, e o valor é estornado integralmente se a síntese falhar.
Limite de 60 requisições por minuto
O limite padrão é de 60 requisições por minuto por chave ativa. Para contas em período de teste, antes da primeira recarga, o limite é de apenas 10 requisições por minuto.
Como as requisições são processadas em fila, tempos de geração podem variar, especialmente em picos de uso.
- Limite padrão: 60 req/min
- Limite pré-recarga: 10 req/min
- Processamento sequencial em fila
Tratamento de erros de API
Erros de validação (como texto inválido ou voz inexistente) retornam códigos de erro específicos. A API garante que não haja cobrança se a síntese falhar.
- Verifique o status HTTP
- Texto acima de 4096 caracteres requer split
- Erros de síntese são gratuitos
Retorno de status HTTP
Respostas 200 indicam sucesso com o arquivo de áudio no corpo. Códigos 4xx indicam erro de cliente (autenticação, formato). Códigos 5xx indicam falha no servidor.
Voices e Models
A lista de vozes disponíveis pode ser obtida via GET /v1/voices, que retorna metadados sobre cada preset, incluindo idiomas suportados e formatos de áudio compatíveis. Este endpoint é essencial para validar a disponibilidade de vozes antes do processamento de áudio.
O endpoint GET /v1/models fornece informações técnicas sobre os motores de síntese (tts-1 e tts-1-hd), permitindo que você ajuste suas integrações com base na complexidade do modelo escolhido para cada caso de uso.
GET /v1/voices para listar vozes
O endpoint retorna a lista completa das 8 vozes disponíveis (Aria, Nova, Luna, Sage, Felix, Milo, Atlas, Orion), com detalhes sobre gênero e características de tom. Cada voz suporta todos os 23 idiomas listados, permitindo seleção precisa sem ambiguidade.
Use esta chamada para mapear IDs de voz aos nomes amigáveis na sua interface de usuário, garantindo que a seleção do usuário corresponda exatamente ao que a API espera.
- Retorna objetos JSON com id, name, gender e tags de estilo.
- Inclui metadados sobre idiomas suportados por cada voz.
- Atualizações de catálogo são refletidas imediatamente.
GET /v1/models para informações técnicas
Retorna informações detalhadas sobre os modelos tts-1 e tts-1-hd, incluindo capacidade de caracteres e formatos de saída suportados. Este endpoint ajuda a validar a compatibilidade antes do envio de requisições pesadas.
Use estas informações para decidir entre o modelo padrão ou o HD com base na qualidade de áudio necessária versus custo por milhão de caracteres.
- Listar modelos disponíveis com IDs e capacidades.
- Detalhar formatos de saída compatíveis.
- Informações sobre limites de caracteres por requisição.
Seleção de voz por ID
Para sintetizar áudio, envie o ID exato da voz (ex: 'aria', 'nova') no campo voice da requisição POST. A API valida se a voz existe e se o idioma está alinhado com o texto fornecido.
Se o idioma não for especificado, a API tenta adivinhar com base no script do texto, mas para textos em latim não-ingleses, defina o campo language explicitamente para evitar erros de pronúncia.
- IDs devem ser enviados em minúsculas.
- Vozes são independentes do idioma do texto.
- A validação é feita em tempo real.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Textos maiores que o limite precisam ser segmentados logicamente.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- Creative Commons Attribution 4.0
- TRON developer hub: TRC-20
- curl documentation
- LibriTTS-R paper (arXiv 2305.18802)
- MDN: Web Speech API
- FFmpeg documentation
- W3C WAI: making audio and video accessible
- Node.js documentation
- OpenAI API reference: create speech
- Python documentation
- IETF RFC 7845: Ogg Opus
