Perguntas frequentes
Como obter a chave API inicial?
Acesse /get-api-key/ e faça login com Google ou e-mail. A chave é exibida na página, iniciando com 'tts-'. Ela é usada no cabeçalho Authorization. Uma conta por site permite uma chave ativa por vez. Novas chaves invalidam a anterior instantaneamente.
Qual é o formato base da requisição?
Use POST em /v1/audio/speech com corpo JSON. Inclua model, input, voice, response_format e speed. O campo language é opcional. O endpoint aceita o mesmo formato da API OpenAI, facilitando a integração direta em sistemas existentes sem necessidade de adaptação complexa.
Posso usar o SDK da OpenAI com esta API?
Sim. Configure o base_url do SDK OpenAI para https://api.h96.info/v1. Use sua chave API ClaraNota. O formato de requisição é idêntico ao da OpenAI, permitindo reutilizar código existente. Basta ajustar a URL base e as credenciais de autenticação.
O que significa o modelo tts-1-hd?
Representa o modelo 'tts-1-hd'. Utiliza o mesmo motor do 'tts-1' e possui o mesmo preço, mas é identificado como 'hd' no campo model. O preço é idêntico para ambos os modelos. Selecione-o via campo 'model' na requisição JSON para obter áudio com maior fidelidade.
Quais formatos de áudio posso solicitar?
Você pode solicitar mp3, wav, opus, flac ou pcm. Especifique o formato desejado no campo response_format da requisição. O formato padrão é mp3. A escolha afeta o tamanho do arquivo e a compatibilidade com seus players ou sistemas de notificação.
O que acontece se exceder 4096 caracteres?
A API aceita no máximo 4096 caracteres por requisição. Para textos maiores, divida o conteúdo em partes menores. Gere o áudio de cada parte separadamente e junte os arquivos resultantes. Isso garante que toda a entrada seja processada corretamente sem erros.
Como funcionam os limites de taxa?
O limite é de 60 requisições por minuto por chave. Antes do primeiro recarga, o limite é de 10 requisições por minuto. Exceder o limite pode resultar em erros temporários. Gerencie suas chamadas para evitar atrasos no processamento das requisições.
O áudio gerado é salvo no servidor?
Não. O áudio é retornado diretamente na resposta da requisição. Não há armazenamento persistente dos arquivos gerados. Apenas metadados da requisição, como tempo e status, são mantidos para fins de cobrança. O texto de entrada não é usado para treinamento.
Existe endpoint para listar vozes?
Sim. Use GET /v1/voices para obter informações sobre vozes, idiomas, formatos e preços disponíveis. Este endpoint retorna a lista de vozes, idiomas, formatos e preços disponíveis. Ideal para interfaces dinâmicas que precisam exibir opções de voz aos usuários finais.
A chave API pode ser revogada manualmente?
Sim. Ao emitir uma nova chave na página /get-api-key/, a chave anterior é invalidada instantaneamente. Não há período de carência. Isso permite revogação imediata em caso de comprometimento ou necessidade de troca. Apenas uma chave ativa por conta.
Como detectar o idioma no texto?
Se o campo language não for definido, o sistema tenta adivinhar o idioma pelo script. Texto em latim assume inglês. Para outros idiomas latinos, defina explicitamente o código ISO. Isso evita detecção incorreta e garante pronúncia adequada para idiomas específicos.
Há suporte para SSML na API?
Não. A API não suporta marcação SSML. Você envia texto puro e o sistema gera áudio automaticamente. Não há suporte para SSML ou controle granular de pausas/entonação via tags. Para ajustes, use os parâmetros de velocidade e escolha de voz disponíveis.
Qual o tempo médio de resposta?
Textos longos são gerados a uma velocidade aproximada de 25 caracteres por segundo de áudio gerado. Sob carga, pode haver espera na fila. Frases curtas levam alguns segundos. Sob carga, as requisições podem entrar em fila e aguardar processamento. A latência varia conforme o volume de solicitações simultâneas na plataforma.
O que é a watermark inaudível?
Cada arquivo de áudio gerado contém uma marca d'água inaudível que indica ser fala sintética. Isso marca o arquivo como fala sintética. A marca não afeta a qualidade sonora nem a experiência do ouvinte final.
Primeira solicitação
curl
curl https://api.h96.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.h96.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.h96.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 API
A autenticação na API ClaraNota utiliza o padrão Bearer Token. Inclua o cabeçalho Authorization: Bearer <sua-chave> em todas as requisições JSON enviadas para https://api.h96.info/v1. O servidor rejeita solicitações sem essa identificação válida.
Uma única chave ativa por conta garante o controle de uso. Ao emitir uma nova chave na interface, a anterior é invalidada imediatamente, encerrando qualquer sessão em curso com o token antigo.
Uso do token Bearer em requisições
Defina o cabeçalho de autorização em cada chamada POST /v1/audio/speech. Isso garante que os caracteres consumidos e os limites de taxa (60 req/min) sejam associados corretamente à sua conta.
Emissão de nova chave invalida a anterior
A segurança é reforçada pela revogação instantânea. Se você gerar uma nova chave no painel, a anterior deixa de funcionar imediatamente, sem necessidade de espera.
Essa característica é útil para rotacionar credenciais em ambientes de desenvolvimento e produção sem sobreposição de acesso.
Visualização da chave na página de conta
- Localize a chave na seção 'API Key'
- Copie e cole no header de autorização
- Gere nova chave para invalidar a anterior
Endpoint principal de síntese
O endpoint principal de síntese é acessível via requisição POST para https://api.h96.info/v1/audio/speech. Este é o único caminho para gerar áudio a partir de texto, seguindo o formato JSON padrão da API de voz.
POST para /v1/audio/speech
Envie o payload para a URL base definida na sua chave de API. A estrutura da requisição é compatível com clientes padrão, permitindo integração direta em sistemas de notificação e interfaces de usuário.
Corpo JSON com campos obrigatórios
Cada solicitação deve incluir o texto a ser convertido no campo input, limitado a 4096 caracteres. É necessário especificar o modelo (tts-1 ou tts-1-hd) e a voz desejada entre as oito opções disponíveis.
- O campo
response_formatdefine o tipo de áudio (mp3, wav, opus, flac, pcm). - O parâmetro
speedajusta a velocidade entre 0.25 e 4.0, se necessário.
Retorno de arquivo de áudio binário
A API retorna o arquivo de áudio binário diretamente no corpo da resposta HTTP. Não há necessidade de buscar o arquivo em outro local; o dado está pronto para ser reproduzido ou armazenado imediatamente.
Campos do corpo da requisição
A requisição POST para síntese de áudio exige a definição do modelo e do texto. O campo model aceita apenas "tts-1" ou "tts-1-hd", ambos utilizando o mesmo motor de síntese e preço. O campo input contém o texto a ser convertido, respeitando o limite máximo de 4096 caracteres por requisição.
Os demais parâmetros ajustam a entrega do áudio. voice seleciona uma das oito vozes pré-definidas. language define o idioma ISO, opcional pois o sistema tenta adivinhar pelo script, mas deve ser explícito para textos latinos não ingleses. response_format escolhe entre mp3, wav, opus, flac ou pcm, enquanto speed ajusta a velocidade entre 0.25 e 4.0.
Modelo tts-1 ou tts-1-hd
O campo model aceita valores "tts-1" ou "tts-1-hd". Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço de $0.01 por 1.000 caracteres. A escolha entre eles não altera o custo nem a qualidade percebida para a maioria dos casos de uso em interfaces.
Essa simplicidade evita complexidade desnecessária na integração. O sistema trata ambos igualmente, garantindo consistência nos resultados gerados para notificações e alertas.
- - Aceita apenas "tts-1" ou "tts-1-hd".
- - Mesmo motor e preço para ambos os valores.
- - Sem diferença funcional relevante para o usuário final.
Texto de entrada até 4096 caracteres
O campo input aceita strings de texto com limite máximo de 4096 caracteres. Espaços e pontuação contam como caracteres. Para textos mais longos, é necessário dividir o conteúdo em partes menores e unir os arquivos de áudio resultantes.
O processamento é sequencial, o que significa que textos longos podem levar tempo para serem gerados. A velocidade média é de aproximadamente 25 caracteres por segundo de áudio gerado.
- - Limite de 4096 caracteres por requisição.
- - Espaços e pontuação contam como caracteres.
- - Textos longos exigem divisão manual e junção posterior.
Voz, idioma e formato de resposta
O campo voice seleciona uma das oito vozes disponíveis: aria, nova, luna, sage, felix, milo, atlas ou orion. O campo language aceita códigos ISO para definir o idioma da fala, sendo recomendado para textos em latim que não sejam inglês.
O campo response_format define o formato do áudio retornado: mp3, wav, opus, flac ou pcm. A escolha deve considerar a compatibilidade do player ou sistema receptor. O campo speed ajusta a velocidade entre 0.25 e 4.0.
- - 8 vozes disponíveis para escolha.
- - Idioma opcional, mas recomendado para não-inglês.
- - Formatos: mp3, wav, opus, flac, pcm.
- - Velocidade ajustável de 0.25 a 4.0.
Formatos de áudio suportados
A API suporta cinco formatos de saída: MP3, WAV, OPUS, FLAC e PCM. A escolha deve considerar a compatibilidade do player final e os requisitos de latência da aplicação. O formato padrão é MP3, equilibrando qualidade e tamanho de arquivo para a maioria dos casos de uso em interfaces web e móveis.
Cada formato tem características técnicas distintas. WAV e FLAC são formatos sem perda, enquanto OPUS e MP3 são formatos comprimidos. PCM é um formato de áudio bruto disponível para download. O tamanho do arquivo varia significativamente entre eles, impactando o tempo de transferência e o armazenamento em cache do cliente.
MP3, WAV, OPUS, FLAC e PCM
O formato MP3 é uma das opções disponíveis. A escolha deve considerar a compatibilidade do player e os requisitos de armazenamento. O WAV é um formato sem perda, mas não há garantia de latência inferior a outros formatos; o tempo de resposta depende da fila de processamento. O OPUS é um formato comprimido disponível para download. A API não oferece streaming ou transmissão em tempo real.
O FLAC mantém a qualidade de estúdio sem compressão com perda, útil para arquivamento ou processamento posterior. O PCM retorna o áudio bruto, sem metadados de codec, adequado para sistemas que realizam decodificação personalizada ou gravação direta em fitas digitais.
- MP3: compressão com perda, ideal para web.
- WAV: sem perda, baixa latência.
- OPUS: alta eficiência em banda limitada.
- FLAC: sem perda, qualidade de estúdio.
- PCM: áudio bruto não comprimido.
Escolha baseada na compatibilidade do player
A seleção do formato deve priorizar a capacidade do player de destino de decodificar o codec especificado. Players HTML5 modernos suportam nativamente MP3, WAV e OPUS. FLAC é um formato suportado pela API. A compatibilidade do player depende do ambiente de execução do cliente.
Para sistemas legados ou hardware embutido, verifique a lista de codecs suportados antes de selecionar o formato. O uso de formatos não compatíveis resultará em falha de reprodução silenciosa, exigindo tratamento de erro no lado do cliente para fallback ou notificação.
- Verifique suporte do player antes de integrar.
- HTML5 suporta MP3 e WAV nativamente. O suporte a OPUS depende do navegador e da versão.
- FLAC pode precisar de codecs adicionais.
- Hardware legado pode não suportar codecs modernos.
Tamanho do arquivo varia pelo formato
O tamanho do arquivo gerado depende diretamente do formato selecionado e da duração do áudio. Formatos sem perda, como WAV e FLAC, resultam em arquivos significativamente maiores que MP3 ou OPUS para a mesma duração.
Para textos longos, o impacto no armazenamento e transferência é maior com formatos não comprimidos. Considere o limite de 4096 caracteres por requisição e a velocidade de geração para estimar o tamanho total do arquivo resultante, especialmente em integrações com limites de banda.
- WAV e FLAC são maiores que MP3/OPUS.
- Tamanho varia com duração e codec.
- Formatos sem perda exigem mais banda.
- Considere limites de requisição para arquivos longos.
Exemplo de uso com cURL
A API aceita entradas diretas via linha de comando, facilitando testes rápidos sem dependência de bibliotecas complexas. O comando abaixo demonstra a estrutura mínima necessária para gerar áudio em MP3, especificando o modelo, a voz e o texto de entrada.
A autenticação é feita via header Bearer, onde a chave da API deve ser inserida exatamente como fornecida na sua conta. O endpoint principal recebe o JSON com as instruções de síntese e retorna o arquivo de áudio binário diretamente.
Comando básico para síntese rápida
Para iniciar, utilize o método POST contra o endpoint de speech. Defina o modelo como 'tts-1' e selecione uma voz, como 'nova'. O texto deve ter no máximo 4096 caracteres. O formato de resposta padrão é MP3, adequado para a maioria dos players de áudio modernos.
- Método: POST
- Endpoint: /v1/audio/speech
- Modelo: tts-1
- Formato: mp3
Headers de autorização incluídos
O cabeçalho Authorization deve conter o token Bearer seguido pela sua chave única. Sem este token, a requisição retornará erro 401. Certifique-se de que a chave esteja correta para evitar falhas de autenticação que não geram cobrança.
Salvamento do áudio em arquivo local
Redirecione a saída padrão para um arquivo .mp3. Este arquivo pode ser reproduzido imediatamente ou integrado ao sistema de notificações da sua aplicação. O tempo de resposta varia conforme a fila de processamento, sendo mais rápido para textos curtos.

Integração com OpenAI SDK
A API ClaraNota adota o mesmo formato de payload do endpoint de fala da OpenAI. Para utilizar as bibliotecas oficiais, basta ajustar o base_url para https://api.h96.info/v1 e configurar o cabeçalho de autenticação com sua chave Bearer. Isso permite reutilizar a infraestrutura de clientes já conhecida.
Essa abordagem elimina a necessidade de wrappers personalizados ou parsing manual de respostas JSON. O código de integração permanece limpo, aproveitando a familiaridade das equipes de produto com as SDKs padrão do mercado.
Alteração do base_url para o endpoint
Configure a URL base da SDK para apontar para https://api.h96.info/v1. O endpoint de síntese permanece em /v1/audio/speech, mantendo a estrutura de requisição JSON idêntica à original.
Uso dos mesmos clientes da biblioteca oficial
Utilize diretamente os clientes fornecidos pela biblioteca oficial. A compatibilidade é garantida pela conformidade estrita com o formato de corpo da requisição, permitindo o envio de parâmetros como model, input e voice sem adaptações complexas.
Compatibilidade com Python e Node.js
As SDKs oficiais para Python e Node.js funcionam imediatamente após a configuração da URL. Isso reduz o tempo de integração para equipes que já dominam essas linguagens, acelerando a implementação de notificações e interfaces sonoras.
Limites de taxa e filas
A taxa de requisições é limitada a 60 requests por minuto por chave de API. Esse limite garante estabilidade no serviço e evita sobrecarga nos servidores de síntese.
60 requisições por minuto por chave
Cada chave válida permite até 60 chamadas ao endpoint de síntese a cada 60 segundos. Esse limite é suficiente para a maioria dos fluxos de notificações em tempo real e processamento em lote.
10 requisições antes do primeiro top-up
Novas contas começam com uma cota reduzida de 10 requisições por minuto antes da primeira recarga. Após adicionar saldo via USDT (TRC-20), o limite padrão de 60 rpm é ativado automaticamente.
Processamento sequencial sob carga
Quando há alta demanda, as requisições são processadas uma após a outra. Isso pode introduzir latência adicional se múltiplos fluxos de áudio forem acionados simultaneamente. Para integrações críticas, considere espaçar as chamadas para evitar filas.
Tratamento de erros comuns
A API retorna códigos HTTP claros para indicar falhas. Erros 401 indicam token inválido ou expirado, enquanto erros 400 sinalizam problemas no corpo da requisição, como exceder o limite de 4096 caracteres.
Em caso de falha na síntese, o valor é devolvido integralmente, garantindo que você não pague por áudio não gerado.
Erros de autenticação 401
Se o token Authorization: Bearer estiver ausente ou incorreto, a API retorna 401. Renove sua chave na página /get-api-key/ para restaurar o acesso imediatamente.
Exceder limite de caracteres 400
O campo input suporta no máximo 4096 caracteres por requisição. Envios acima deste limite geram erro 400. Divida textos longos em partes menores para garantir o processamento.
Falha na síntese com reembolso automático
Se a síntese falhar durante o processamento, o crédito correspondente é estornado automaticamente. Você não paga por áudio não gerado, mantendo o controle preciso dos custos da sua aplicação.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Em caso de falha persistente após múltiplas retentativas, exiba o texto original na interface do usuário.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- LibriTTS-R corpus (OpenSLR 141)
- W3C WAI: making audio and video accessible
- openai-python on GitHub
- curl documentation
- OpenAI API reference: create speech
- TRON developer hub: TRC-20
- LibriVox public-domain audiobooks
- FFmpeg documentation
- LibriTTS-R paper (arXiv 2305.18802)
- Tether (USDT)
- openai-node on GitHub
