Perguntas frequentes
Como escolher a voz ideal para um app de finanças?
Para finanças, priorize clareza e neutralidade. Atlas (masculino) é ideal para notícias e dados neutros. Sage (feminino) oferece tom instrucional e calmo, perfeito para tutoriais. Evite vozes muito energéticas como Felix ou Nova, que podem parecer pouco profissionais em contextos de alertas financeiros ou explicações detalhadas de transações.
Qual formato de áudio economiza mais banda?
O formato opus oferece a melhor compressão para economizar banda, mantendo boa qualidade. Mp3 é uma alternativa leve e amplamente suportada. Flac e wav são sem perda ou sem compressão, resultando em arquivos maiores. Pcm é formato bruto, consumindo mais banda. Escolha opus para eficiência máxima em redes móveis.
O que é watermark inaudível e para que serve?
Cada arquivo gerado contém uma marca d'água inaudível que identifica o áudio como fala sintética. Isso serve para indicar claramente que o conteúdo não foi gravado por humanos, garantindo transparência para o usuário final. É uma característica técnica automática de todos os arquivos produzidos pela API, sem custo adicional.
Posso usar múltiplas chaves API simultaneamente?
Sim, você pode emitir uma nova chave a qualquer momento. A chave anterior é invalidada imediatamente. Isso permite rotatividade ou uso em diferentes ambientes, mas cada conta possui apenas uma chave ativa por vez. Cada chave tem limite de 60 requisições por minuto. Para alto volume, considere distribuir requisições entre contas ou gerenciar filas para respeitar os limites de taxa.
Como otimizar textos para síntese rápida?
Mantenha textos abaixo de 4096 caracteres por solicitação para evitar divisão. A velocidade média é de 25 caracteres por segundo. Use pontuação adequada para pausas naturais. Evite caracteres especiais complexos que possam confundir o motor. Teste trechos curtos primeiro para ajustar a velocidade (0.25–4.0) e garantir que o áudio final atenda aos requisitos de UX.
A velocidade de fala (speed) afeta o custo?
Não. O custo é baseado no número de caracteres do texto de entrada, não na duração do áudio gerado. Alterar a velocidade entre 0.25 e 4.0 muda apenas a duração final, mas não o preço. Você paga $0.01 por mil caracteres, independentemente de a voz falar rápido ou devagar.
Existe diferença técnica entre tts-1 e tts-1-hd?
Ambos usam o mesmo motor de síntese e têm o mesmo preço. A escolha entre 'tts-1' e 'tts-1-hd' no campo 'model' não altera o custo nem a qualidade básica percebida. Ambos aceitam os mesmos parâmetros de voz, idioma e formato. Use qualquer um conforme preferência de nomenclatura no código, sem impacto financeiro.
Como monitorar o uso de caracteres na API?
A página /get-api-key/ exibe o saldo, créditos restantes e histórico de uso. O sistema registra metadados de tempo, caracteres e status para faturamento. Você pode calcular o custo dividindo os caracteres processados por 100.000 e multiplicando por $1,00. Use a chave API para acessar dados de uso via endpoints disponíveis.
Devo usar cache para textos frequentes?
Sim, é recomendado. Como o áudio é gerado sob demanda e não armazenado pelo serviço, você deve gerenciar o cache localmente. Armazenar o arquivo de áudio (mp3, opus, etc.) para textos idênticos evita novas chamadas de API, economizando caracteres e reduzindo latência. A API não oferece armazenamento de áudio persistente.
Qual a diferença entre USDT e pagamentos tradicionais?
Aceitamos apenas USDT na rede TRON (TRC-20), com mínimo de $5. Não há cartões, PayPal, assinaturas ou faturas com IVA. O crédito é creditado automaticamente em minutos. Não há planos mensais ou gastos mínimos. Esta abordagem simplifica o pagamento global, mas requer conhecimento básico de criptomoedas e carteira digital para transações.
As vozes funcionam bem em português do Brasil?
Sim, o português está na lista de 23 idiomas suportados. Todas as 8 vozes podem falar português. Se não definir o parâmetro 'language', o sistema pode assumir inglês para texto em latim. Para garantir a pronúncia correta do português do Brasil, defina explicitamente 'language': 'pt-BR' ou 'pt' na requisição.
Há limite de uso gratuito contínuo?
Não há limite contínuo gratuito. O trial inicial dá $0,50 (50.000 caracteres) por 7 dias ao usar login Google. Contas por e-mail começam sem crédito. Após o trial, você precisa recarregar via USDT. Não há plano gratuito recorrente nem limite de caracteres contínuo sem pagamento. O saldo não expira.
O SDK da OpenAI suporta todos os parâmetros?
O SDK da OpenAI funciona alterando 'base_url' para https://api.h96.info/v1. Ele suporta os parâmetros principais: model, input, voice, response_format e speed. O parâmetro 'language' é suportado pela API, mas pode variar a compatibilidade dependendo da versão do SDK da OpenAI. Verifique a documentação do SDK para compatibilidade exata de campos opcionais como 'language' em versões antigas.
Como testar a API antes de ir para produção?
Use o trial de $0,50 disponível ao entrar com Google. Execute requisições curl ou via SDK para testar vozes, formatos e velocidades. Verifique o saldo na página /get-api-key/. Teste textos longos para confirmar a divisão em partes de 4096 caracteres. Monitore o status da resposta para garantir que a síntese foi concluída com sucesso.
Escolha de vozes por tipo de interface
A escolha da voz impacta diretamente a experiência do usuário em interfaces digitais. Diferentes contextos de uso exigem timbres específicos para garantir clareza e adequação ao tom da aplicação.
Vozes neutras para dashboards corporativos
Atlas é uma escolha adequada para notificações em painéis de controle. Sua voz neutra e clara transmite informações sem distrair o usuário durante tarefas analíticas.
Vozes amigáveis para apps de consumo
Nova e Milo oferecem tons vibrantes e conversacionais, ideais para aplicativos que buscam criar uma conexão mais próxima e menos técnica com o usuário final.
Vozes institucionais para notificações oficiais
Para comunicados formais, Orion e Sage proporcionam uma sonoridade séria e confiável, adequada para alertas críticos ou informações que exigem tom institucional.
Otimização de texto para síntese
O limite de 4096 caracteres por requisição exige que textos longos sejam divididos logicamente antes do envio. Cada parte gerada deve ser concatenada para manter a fluidez da fala, evitando cortes abruptos que prejudiquem a compreensão em notificações ou alertas de sistemas.
Para garantir eficiência, remova caracteres especiais desnecessários e utilize pontuação adequada. A vírgula e o ponto criam pausas naturais, enquanto a velocidade ajustável entre 0,25x e 4,0x permite adaptar o ritmo conforme o contexto da interface do usuário.
Quebra lógica antes de 4096 caracteres
Divida o texto em segmentos menores que respeitem o limite técnico da API. Isso previne falhas de síntese e garante que cada parte seja processada corretamente, mantendo a integridade semântica da mensagem final.
Utilize algoritmos de segmentação que identifiquem finais de frase ou parágrafos. Assim, a junção dos arquivos de áudio resultantes soa mais coerente para o usuário final.
- Máximo de 4096 caracteres por chamada POST
- Concatenar arquivos resultantes para formar a mensagem completa
Remoção de caracteres especiais desnecessários
Símbolos como asteriscos ou tags HTML podem interferir na pronúncia. Limpe o input antes do envio para evitar ruídos na síntese, especialmente em interfaces que recebem texto formatado de bases de dados.
Isso reduz caracteres desnecessários que contam para o limite e para o custo, otimizando o uso do crédito disponível na conta.
Uso de pontuação para pausas naturais
Pontos finais e vírgulas definem o ritmo da fala sintética. Textos com pontuação clara soam mais profissionais e compreensíveis em dashboards corporativos e notificações de alerta.
Evite excesso de reticências ou travessões, que podem gerar pausas não intuitivas. A clareza textual é essencial para a experiência do usuário em apps de consumo.
- Use vírgulas para pausas curtas
- Pontos finais para encerrar frases completas
Seleção de formatos de áudio
O formato de áudio impacta diretamente na latência de carregamento e no consumo de dados do seu aplicativo. A escolha depende do equilíbrio entre fidelidade sonora e eficiência de rede, considerando que cada requisição retorna um arquivo completo sem streaming.
MP3 para balanceamento entre qualidade e tamanho
O MP3 oferece uma boa relação entre tamanho de arquivo e clareza para a maioria dos casos de uso. Ideal para notificações push e alertas em sistemas web, garantindo reprodução rápida sem desperdício de banda.
OPUS para redução de banda em mobile
Para aplicativos móveis com dados limitados, o OPUS reduz significativamente o tamanho do arquivo mantendo inteligibilidade. Economiza tráfego de dados dos usuários finais, essencial para atualizações frequentes de status ou alertas em segundo plano.
FLAC para qualidade de auditoria
O formato FLAC fornece áudio sem perda de qualidade, adequado para registros auditivos ou compliance. Utilize quando a fidelidade original da voz sintética for crítica para verificação de conteúdo, mesmo ocupando mais espaço.
Gestão de limites de taxa
O limite padrão é de 60 requisições por minuto por chave, com uma cota reduzida de 10/min até o primeiro recarga. Para equipes de produto que integram notificações em massa, exceder essa taxa resulta em erro 429. Monitorar o uso em tempo real evita interrupções no fluxo de áudio dos alertas.
Implementar um bucket de tokens ou usar cabeçalhos de resposta para rastrear o consumo garante que as requisições não sejam bloqueadas abruptamente. Isso mantém a estabilidade da interface mesmo durante picos de envio de alertas críticos.
Monitoramento de requisições por minuto
Rastreie o contador de solicitações enviadas por minuto. O endpoint de status da chave mostra o uso atual, permitindo ajustes dinâmicos na frequência de geração de áudio (ver /get-api-key/).
Defina um limite seguro, como 50 requisições/min, para manter uma margem de segurança contra latência variável sob alta demanda.
- Verificar contador antes de cada lote de notificações
- Ajustar frequência conforme o status da chave API
Implementação de filas internas
Use uma fila interna (ex: Redis ou RabbitMQ) para sequenciar as chamadas à API. Isso garante que, mesmo com múltiplos eventos acionando notificações simultâneas, o limite de 60 req/min seja respeitado sem perda de dados.
Processadores assíncronos podem consumir a fila a uma taxa constante, liberando recursos do servidor principal.
- Usar filas para ordenar e espaçar requisições
- Separar geração de áudio do evento de disparo inicial
Retardo suave para evitar bloqueios
Implemente um delay exponencial suave entre lotes de requisições. Se a API retornar 429, aguarde alguns segundos antes de tentar novamente.
Isso evita o efeito de 'thundering herd', onde múltiplos clientes tentam reenviar simultaneamente após uma queda temporária de capacidade.
- Backoff exponencial ao receber erro 429
- Exponenciação suave para evitar picos de reconexão
Tratamento de erros e falhas
Quando a síntese falha, o consumo é estornado integralmente, garantindo que não haja cobrança por requisições inválidas. A API retorna códigos de erro HTTP claros para indicar problemas de autenticação, limites de taxa excedidos ou erros de modelo. Identificar esses códigos permite ajustar o comportamento do cliente antes de novas tentativas.
Implementar lógica de retentativa com backoff exponencial é essencial para lidar com a fila de processamento. Em picos de demanda, as requisições podem aguardar por serialização. Um atraso progressivo entre tentativas evita o congestionamento e respeita o limite de 60 requisições por minuto por chave, reduzindo erros 429.
Identificação de códigos de erro HTTP
Utilize a resposta JSON para distinguir entre erros de cliente (4xx) e problemas de servidor (5xx). Erros 401 indicam chave inválida ou expirada, enquanto 429 sinalizam que o limite de 60 req/min foi atingido. Tratar esses códigos imediatamente evita desperdício de caracteres e custos desnecessários.
- Códigos 4xx geralmente requerem ação imediata do desenvolvedor
- Códigos 5xx podem ser seguros para retentativa com delay
Retentativa com backoff exponencial
Configure seu cliente para aumentar o tempo de espera entre tentativas. Comece com 500ms e dobre o tempo a cada falha consecutiva. Isso permite que a fila de processamento da API esvazie naturalmente, especialmente durante picos de uso onde a latência aumenta significativamente.
- Início recomendado: 500ms
- Máximo sugerido: 8 segundos
Fallback para texto se áudio falhar
Em caso de falha persistente após múltiplas retentativas, exiba o texto original na interface do usuário. Como não há streaming, garantir a disponibilidade da informação é prioritário. O áudio pode ser carregado assincronamente em segundo plano se o contexto permitir.
Integração com OpenAI SDK
A API ClaraNota é compatível com os SDKs oficiais da OpenAI, exigindo apenas a reconfiguração do base_url para https://api.h96.info/v1 e o uso da chave de API (tts-...) no cabeçalho de autenticação. Essa abordagem permite reutilizar bibliotecas existentes em Python ou Node.js sem adaptações complexas.
Para equipes de produto que integram notificações, o uso de clientes assíncronos melhora a responsividade da interface. A biblioteca lida com a serialização JSON padrão, facilitando o envio de textos e a recepção dos arquivos de áudio gerados.
Configuração correta do base_url
Defina a variável de ambiente OPENAI_API_BASE ou passe base_url diretamente no construtor do cliente. O endpoint deve apontar para https://api.h96.info/v1, mantendo a mesma estrutura de payload da OpenAI, mas utilizando suas credenciais específicas.
- Endpoint:
https://api.h96.info/v1 - Autenticação:
Authorization: Bearer tts-... - SDKs: Python, Node.js, cURL
Uso de clientes assíncronos para performance
Utilize clientes assíncronos (AsyncOpenAI) para evitar bloqueios de thread em aplicações web concorrentes. Isso permite que múltiplas solicitações de síntese sejam enfileiradas sem travar a interface do usuário, crucial para alertas simultâneos.
Tratamento de timeouts na biblioteca
Defina timeouts generosos, pois a latência varia conforme a fila de processamento. Textos longos podem demorar mais que o padrão. Configure retentativas exponciais para lidar com picos de demanda sem perder requisições críticas de notificação.
Testes de qualidade de áudio
A validação da qualidade sintética exige testes sistemáticos em todos os 23 idiomas suportados, desde o árabe até o turco. A clareza deve ser verificada tanto para textos em scripts latinos quanto em caracteres asiáticos, garantindo que a pronúncia permaneça natural e compreensível.
Além da clareza, é crucial ajustar a velocidade entre 0.25x e 4.0x para encontrar o equilíbrio ideal entre naturalidade e eficiência. Para notificações rápidas, velocidades mais altas podem ser aceitas, enquanto para narrativas, a velocidade padrão garante melhor compreensão. A latência variável sob carga deve ser considerada nos testes.
Avaliação de clareza por idioma ['Verifique a pronúncia em cada um dos 23 idiomas suportados. Para textos em alfabeto latino que não sejam inglês, defina o parâmetro language explicitamente para evitar falhas na detecção automática.', 'Teste frases típicas de cada interface, como alertas de sistema ou mensagens de confirmação, em todos os idiomas disponíveis.'] ['Use o endpoint GET /v1/voices para confirmar a disponibilidade de vozes por idioma.', 'Teste a transição de idiomas no mesmo texto para avaliar a consistência.']
Testes de velocidade (0.25x a 4.0x) ['Ajuste o parâmetro speed para adaptar o ritmo às necessidades da interface. Velocidades mais altas podem reduzir o tempo de geração, mas podem comprometer a clareza.', 'Realize testes de usabilidade com usuários reais para determinar a velocidade ideal para cada tipo de notificação ou instrução.'] ['Teste velocidades de 0.5x, 1.0x, 2.0x e 4.0x.', 'Meça o tempo de resposta da API em diferentes velocidades.']
Verificação de watermark inaudível ["Cada arquivo de áudio gerado contém uma marca d'água inaudível que identifica o conteúdo como síntese artificial. Esta marca não interfere na experiência do usuário, mas é crucial para a conformidade e transparência.", 'Verifique a presença do watermark em diferentes formatos de saída (mp3, wav, opus, flac, pcm) para garantir sua persistência em todas as integrações.'] ['Confirme a presença do watermark em amostras de áudio geradas.', 'Verifique se o watermark é consistente em diferentes vozes e idiomas.']

Cálculo de custos por cenário
Calcular o custo exato depende do volume de caracteres, pois a tarifa é de US$ 0,01 por mil caracteres. Para equipes de produto, entender essa métrica é essencial para orçar notificações em massa sem surpresas na fatura mensal.
A transparência no preço permite prever gastos com precisão, especialmente ao integrar a API em sistemas de alertas ou interfaces com linguagem natural que processam grandes volumes de texto diariamente.
Simulação para 1000 notificações diárias
Considerando uma média de 50 caracteres por notificação, o volume diário seria de 50.000 caracteres. Com o crédito gratuito de US$ 0,50 (válido por 7 dias), os primeiros 50.000 caracteres são cobertos inicialmente.
Após o esgotamento do trial, o custo seria de US$ 0,50 por dia, totalizando aproximadamente US$ 15,00 mensais. Esse valor é fixo, independente do número de requisições, desde que respeitado o limite de 60 requisições por minuto.
- Custo diário estimado: US$ 0,50
- Volume total: 50.000 caracteres/dia
- Limite de taxa: 60 req/min
Impacto de textos longos no orçamento
Textos acima de 4096 caracteres devem ser divididos em partes. Cada parte gera uma requisição independente, mas o preço é calculado pelo total de caracteres processados.
Se um alerta de sistema possui 20.000 caracteres, o custo será de US$ 0,20. O tempo de processamento pode variar, mas o custo permanece linear ao volume de texto enviado.
- Texto > 4096 chars: dividir e concatenar
- Custo linear por caractere
- Falhas são gratuitas
Otimização para reduzir caracteres repetidos
Pontuação e espaços contam como caracteres. Remover espaços desnecessários ou abreviar textos repetitivos reduz diretamente o custo.
Exemplo: 'O sistema vai falhar' (19 chars) vs 'O sistema vai falhar!' (20 chars). Pequenas economias se acumulam em alta escala.
Use a API para testar diferentes vozes sem custo adicional se a síntese falhar, garantindo a escolha mais eficiente para seu caso de uso.
- Espaços contam como caracteres
- Remova redundâncias
- Teste vozes sem custo em falhas
Arquitetura escalável
Para escalar o uso da API em aplicativos de notificação, o caching de áudio gerado é essencial. Como os textos de alerta são frequentemente repetitivos, armazenar os arquivos em uma CDN reduz drasticas chamadas à API e os custos associados.
Isso garante latência mínima para o usuário final, entregando o áudio instantaneamente sem depender da fila de processamento em tempo real da API.
Uso de CDN para áudio cacheado
Armazene os arquivos de áudio gerados em um CDN global. Isso evita requisições redundantes para textos idênticos, economizando caracteres e tempo de processamento.
Ideal para notificações padrão como "seu pedido foi enviado" ou lembretes de agendamento que se repetem frequentemente.
- Cache keys baseadas no hash do texto e voz
- TTL configurável conforme a frequência de atualização do conteúdo
Balanceamento de carga entre chaves API
Com o limite de 60 requisições por minuto por chave, distribua as chamadas entre múltiplas chaves ativas se o volume for alto.
Crie um balanceador simples no backend que alterna entre chaves para evitar gargalos durante picos de notificações simultâneas.
- Gere chaves adicionais conforme necessário
- Distribua requisições de forma round-robin
Monitoramento de métricas de uso
Acompanhe o consumo de caracteres e o status das requisições para prever esgotamento do saldo.
Monitore a taxa de sucesso para identificar se a fila de processamento está causando atrasos significativos.
Use esses dados para ajustar o tamanho dos lotes de notificações e otimizar custos.
- Alertas de saldo baixo
- Métricas de latência por voz
Acessibilidade e conformidade
A API ClaraNota facilita a inclusão digital ao fornecer áudio gerado por síntese de voz, um componente essencial para interfaces acessíveis. Ao integrar respostas em áudio, você permite que usuários com deficiência visual ou dificuldades de leitura naveguem pelo seu sistema com autonomia, complementando ou substituindo elementos visuais de texto.
A conformidade com padrões de acessibilidade (como WCAG) depende da implementação da equipe, mas a API fornece as ferramentas para implementá-las de forma consistente e escalável.
Suporte a leitores de tela
O áudio gerado pela API é estruturado de forma clara e natural, facilitando a interpretação por tecnologias assistivas como NVDA, JAWS ou VoiceOver. Ao invés de depender apenas de atributos ARIA estáticos, o texto convertido em voz oferece uma experiência mais fluida e contextual.
Lembre-se que a clareza da pronúncia depende do idioma configurado e da voz selecionada. Teste sempre com o leitor de tela ativo para garantir que as pausas e entonação são interpretadas corretamente pelo software do usuário.
- Configure o atributo
langcorretamente no corpo da requisição para garantir a pronúncia adequada. - Teste a saída de áudio em conjunto com os principais leitores de tela do mercado.
Opção de desligar áudio por usuário
A API não impõe persistência de estado; cabe ao seu aplicativo gerenciar a preferência do usuário. Implemente um toggle na interface para permitir que o usuário desative a reprodução automática de notificações ou alertas.
Isso é crucial para respeitar a acessibilidade de quem pode ser sensível a estímulos sonoros constantes ou preferir ler o texto alternativo em vez de ouvi-lo.
- Armazene a preferência de áudio no perfil do usuário ou no estado local do app.
- Respeite as configurações de
prefers-reduced-motionou equivalentes de acessibilidade do sistema operacional.
Clareza em ambientes com ruído
Em ambientes corporativos ruidosos ou em uso móvel, a clareza da voz é vital. Utilize vozes como sage (calma, instrucional) ou atlas (neutra, notícias) para garantir que a informação seja compreendida mesmo com interferência sonora.
Ajuste a velocidade (speed) para níveis moderados (1.0 a 1.2) se o ambiente for muito ruidoso, garantindo que cada sílaba seja articulada sem ambiguidade.
- Priorize vozes masculinas neutras ou femininas claras para maior intelligibility em ruído.
- Evite velocidades extremas (>2.0x) em ambientes externos ou de alta distração.
Limitações técnicas a considerar
Esta seção detalha limitações técnicas específicas da API ClaraNota que impactam o design de interfaces e a experiência do usuário final.
Conhecer essas restrições permite evitar expectativas equivocadas sobre controle de prosódia, latência instantânea e formatos de áudio em tempo real.
Ausência de SSML para controle fino
A API não suporta marcação SSML, o que elimina a possibilidade de controlar pausas precisas, entonação ou pronúncia customizada de palavras específicas. Para ajustes finos, é necessário ajustar a pontuação no texto de entrada ou variar a velocidade global.
Sem streaming para atualização em tempo real
A síntese retorna o arquivo de áudio completo apenas após o processamento final. Não há transmissão parcial de áudio, o que significa que o usuário deve aguardar o fim da geração para iniciar a reprodução, mesmo em textos curtos.
Latência variável sob alta demanda
Pedidos são processados sequencialmente. Sob alta carga, as requisições podem ficar em fila, aumentando o tempo de resposta. Para textos longos, a velocidade é aproximadamente em tempo real (25 caracteres por segundo), mas frases curtas podem levar alguns segundos para gerar.
Exemplo de fluxo completo
Este guia descreve o fluxo técnico completo para integrar a API de TTS em sistemas de notificação, desde a solicitação até a reprodução no cliente.
Requisição de texto para áudio
Envie um POST para https://api.h96.info/v1/audio/speech com o texto (até 4096 caracteres), modelo e voz. O corpo JSON deve incluir input, voice e response_format, autenticado via header Authorization: Bearer.
Recebimento e armazenamento temporário
A API retorna o arquivo de áudio diretamente na resposta. Para notificações, armazene-o temporariamente ou reproduza-o imediatamente. Lembre-se de que os dados de entrada não são usados para treinamento.
Reprodução no frontend do aplicativo
Reproduza o áudio recebido no cliente. Como não há streaming, o arquivo completo deve ser carregado antes da reprodução. Use o formato MP3 para equilíbrio ou OPUS para economia de banda.
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.
