Perguntas frequentes
O que é necessário para começar?
Crie uma conta em /get-api-key/ via Google ou e-mail. Você receberá uma chave Bearer e um saldo inicial de US$ 0,50 (válido por 7 dias) apenas se criar a conta com login Google. Para uso contínuo, realize um top-up mínimo de US$ 5 via USDT (TRC-20). Não há planos mensais ou custos fixos, apenas pagamento por caractere processado.
Como funciona a autenticação com chave?
Envie o cabeçalho Authorization: Bearer tts-... em cada requisição. Cada conta possui uma chave ativa; ao emitir uma nova, a anterior é invalidada imediatamente. Isso garante segurança simples sem necessidade de gerenciamento complexo de tokens ou sessões para a integração do seu aplicativo móvel.
Posso usar o SDK oficial da OpenAI?
Sim. A API segue o mesmo formato de requisição do endpoint de fala da OpenAI. Utilize os SDKs oficiais da OpenAI, ajustando apenas a URL base para https://api.air123.cc/v1. Isso permite reutilizar o código de integração existente sem necessidade de bibliotecas proprietárias adicionais.
Qual base_url configurar no SDK?
Configure a URL base para https://api.air123.cc/v1. As requisições devem ser enviadas para POST /v1/audio/speech com o corpo JSON contendo model, input, voice, response_format e speed. Esta configuração garante compatibilidade total com clientes HTTP padrão e SDKs compatíveis com OpenAI.
Quais formatos de áudio usar no mobile?
Você pode escolher entre mp3, wav, opus, flac ou pcm. Para mobile, opus ou mp3 são recomendados para eficiência de banda. O formato PCM é útil para processamento direto. O formato selecionado é definido no campo response_format da requisição JSON enviada ao endpoint de síntese.
Como lidar com textos acima de 4096 caracteres?
A API limita cada requisição a 4096 caracteres. Você deve dividir o texto maior em partes dentro desse limite e enviar múltiplas requisições. Em seguida, junte os arquivos de áudio gerados sequencialmente para reproduzir o conteúdo completo no seu aplicativo móvel de forma contínua.
O que acontece ao exceder 60 requisições por minuto?
O limite é de 60 requisições por minuto por chave. Antes do primeiro top-up, o limite é de 10 requisições por minuto. Se exceder, as requisições podem ser rejeitadas ou processadas com atraso. Monitore o uso no painel para ajustar a taxa de geração conforme a demanda do app.
A velocidade afeta o tempo de geração?
Sim, a velocidade (0.25–4.0) altera a duração do áudio, mas o tempo de processamento da API permanece baseado na taxa real de geração. Textos longos levam cerca de 25 caracteres por segundo. Ajustar a velocidade não acelera necessariamente o tempo de resposta da API sob carga.
Posso definir o idioma explicitamente?
Sim, use o campo language com o código ISO. Se omitido, o idioma é inferido pelo script (texto latino assume inglês). Para textos em latim não ingleses, defina explicitamente para garantir a pronúncia correta. Idiomas como vietnamita, indonésio, tailandês, ucraniano, romeno, checo, bengali e outros não listados não são suportados.
Os áudios são armazenados após a geração?
Não. O áudio gerado é retornado na resposta e não é armazenado pelos nossos servidores. Apenas metadados da requisição (tempo, caracteres, status) são mantidos para fins de faturamento. O texto de entrada é usado exclusivamente para produzir o áudio e não para treinamento de modelos.
Como rastrear erros na integração?
Requisições com falha são gratuitas e o valor é estornado. O painel de controle exibe o histórico de uso, status e caracteres consumidos. Use as respostas HTTP padrão da API para detectar erros em tempo real. O suporte é exclusivo por e-mail para dúvidas técnicas.
Posso reutilizar chaves após troca?
Ao emitir uma nova chave, a anterior é invalidada imediatamente. Você não pode usar ambas simultaneamente. Isso garante que apenas uma credencial esteja ativa por conta. Registre a nova chave em seus serviços de backend antes de descontinuar o uso da chave antiga.
Há suporte para streaming de áudio?
Não. A API retorna o arquivo de áudio completo após o processamento. Não há streaming WebSocket ou áudio parcial em tempo real. Para apps móveis, isso significa que o usuário deve aguardar o fim da síntese antes de iniciar a reprodução, a menos que você implemente buffer.
Existe SDK nativo para iOS ou Android?
Não. Não oferecemos SDKs nativos específicos para iOS ou Android. Utilize o SDK oficial da OpenAI com a URL base ajustada ou faça requisições HTTP padrão. A integração é feita via REST API, compatível com qualquer cliente HTTP moderno disponível nas plataformas móveis.
Pré-requisitos da integração
Para integrar SomLeve em seu app móvel, o primeiro passo é garantir que sua infraestrutura esteja preparada para a comunicação com a API. Você precisará de uma conta ativa no site air123.cc e de uma chave API válida, que autoriza suas solicitações de síntese de voz.
Além da credencial, verifique seu saldo ou utilize o crédito de teste gratuito de $0,50 disponível ao entrar com o Google. Ter conhecimento básico de HTTP e JSON é essencial, pois a integração funciona exatamente como o SDK oficial da OpenAI, facilitando a adoção por equipes de produto.
Conta com chave API válida
Crie sua conta em /get-api-key/ selecionando login com Google ou e-mail. Uma chave única será gerada e exibida na dashboard, pronta para ser copiada para seu código.
Saldo ou crédito de teste
O crédito de $0,50 permite testar cerca de 50.000 caracteres sem compromisso. Para uso contínuo, o saldo é recarregado via USDT (TRC-20), sem mensalidades fixas.
Conhecimento de HTTP e JSON
A API aceita requisições POST em formato JSON. Você deve configurar o cabeçalho Authorization com sua chave e definir os parâmetros do modelo e entrada de texto.
Primeira requisição com curl
A primeira integração começa com uma requisição HTTP direta, evitando dependências pesadas. O endpoint POST https://api.air123.cc/v1/audio/speech aceita JSON e retorna o arquivo de áudio diretamente. Esta abordagem permite testes rápidos antes de implementar a lógica complexa no aplicativo móvel.
Usar curl facilita a validação imediata da chave API e da disponibilidade do serviço. Você pode ajustar parâmetros básicos como modelo e voz para garantir que o output atenda aos requisitos de qualidade antes de codificar a integração definitiva.
Comando POST para /v1/audio/speech
Envie uma requisição POST para o endpoint especificado. O corpo da mensagem deve conter o texto a ser convertido e as configurações de áudio. A resposta conterá o arquivo binário do áudio.
Este método é independente de linguagem, utilizando apenas HTTP padrão. É ideal para validar credenciais e limites de taxa antes do desenvolvimento completo.
- Endpoint:
POST https://api.air123.cc/v1/audio/speech - Método: HTTP POST
- Formato: JSON
Parâmetros model, input e voice
Os parâmetros essenciais são model ("tts-1" ou "tts-1-hd"), input (texto até 4096 caracteres) e voice (uma das 8 vozes disponíveis). O parâmetro input aceita textos em qualquer um dos 23 idiomas suportados.
A escolha do modelo define a qualidade e o preço. Ambos os modelos utilizam o mesmo motor de síntese, garantindo consistência no resultado final independente da escolha.
Salvamento do áudio retornado
O arquivo de áudio gerado deve ser salvo diretamente no dispositivo ou processado em memória. Formatos como mp3 ou opus são recomendados para eficiência.
Certifique-se de que o aplicativo móvel possa lidar com o tamanho do arquivo. Para textos longos, o áudio será dividido em partes gerenciáveis.
Uso do SDK OpenAI
O SDK oficial da OpenAI funciona diretamente com a API do SomLeve, exigindo apenas uma alteração mínima de configuração. Ao apontar a propriedade base_url para https://api.air123.cc/v1, as bibliotecas utilizam os mesmos endpoints nativos, facilitando a integração em apps móveis sem a necessidade de adapters personalizados.
Configuração da base_url
Para utilizar o SDK, defina a URL base como https://api.air123.cc/v1. Isso redireciona todas as chamadas para a infraestrutura do SomLeve, mantendo a compatibilidade total com o ecossistema existente da OpenAI.
Mesma forma de payload OpenAI
O corpo da requisição segue exatamente o formato padrão: model, input e voice. Não há necessidade de mapear campos adicionais, o que simplifica o desenvolvimento de clientes iOS e Android que já consomem áudio via JSON.
Compatibilidade com bibliotecas oficiais
Qualquer biblioteca oficial da OpenAI (Node.js, Python, Swift, etc.) é compatível desde que a URL base seja ajustada. Isso permite reutilizar código de geração de áudio existente, reduzindo o tempo de integração em projetos mobile.
Formatação para mobile
Escolher o formato de áudio impacta diretamente a experiência do usuário final e o consumo de dados móveis. O mp3 oferece compatibilidade universal, enquanto o opus proporciona compressão mais eficiente, ideal para conexões móveis variáveis.
Escolha entre mp3 e opus
O mp3 é a escolha padrão para máxima compatibilidade em todos os dispositivos iOS e Android. Já o opus reduz significativamente o tamanho do arquivo, mantendo qualidade auditiva adequada para narrativas e TTS rápido.
- Use mp3 para garantir reprodução em players nativos antigos
- Prefira opus para economizar banda em redes 3G/4G
Redução de tamanho e banda
Arquivos menores aceleram o download e reduzem o uso de dados do usuário. Isso é crucial para apps que entregam conteúdo gerado sob demanda em ambientes móveis.
Decodificação nativa em iOS/Android
Tanto iOS quanto Android possuem decodificadores nativos para mp3 e opus. Isso elimina a necessidade de bibliotecas externas pesadas, mantendo o app leve e responsivo.
Controle de velocidade
A velocidade de síntese é ajustável via parâmetro speed no corpo da requisição, aceitando valores entre 0.25 e 4.0. Isso permite desde narração calma até leitura acelerada, sem alterar a voz base selecionada.
Range de 0.25 a 4.0
O API aceita qualquer valor decimal dentro desse intervalo. Valores abaixo de 1.0 ralentizam a fala, úteis para dicção clara. Valores acima de 1.0 aceleram a fala, mantendo a entonação natural da voz escolhida.
- Valor mínimo: 0.25 (muito lento)
Ajuste para narrativas ou TTS rápido
Para apps de audiolivros ou instruções detalhadas, velocidades entre 0.8 e 1.2 garantem clareza. Em notificações ou alertas, valores próximos de 1.5 ou 2.0 reduzem o tempo de espera do usuário final.
Impacto no tempo de geração
Aumentar a velocidade reduz proporcionalmente o tempo de geração do áudio. Como o processamento é sequencial, textos longos podem ficar na fila; ajustar a velocidade ajuda a prever melhor o tempo total de entrega do arquivo.
Tratamento de textos longos
O limite de entrada é de 4096 caracteres por solicitação, contando espaços e pontuação. Para narrativas mais extas, o texto deve ser dividido manualmente em blocos menores antes de enviar as requisições sequenciais à API.
Divisão em blocos de 4096 caracteres
Cada chamada POST processa no máximo 4096 caracteres. É responsabilidade do aplicativo segmentar o texto de entrada, garantindo que nenhuma requisição exceda esse limite para evitar erros de validação.
Concatenação dos arquivos de áudio
A API retorna arquivos de áudio independentes para cada bloco processado. O aplicativo deve armazená-los temporariamente e concatená-los em memória ou disco antes da reprodução, mantendo a ordem sequencial para garantir a fluidez da narrativa.
Gerenciamento de memória no app
Textos longos geram múltiplos arquivos de áudio simultâneos. É crucial liberar a memória dos blocos já reproduzidos para evitar que o app consuma muitos recursos, especialmente em dispositivos móveis com limitações de RAM.
Idioma e detecção
A API permite definir o idioma explicitamente ou confia na detecção automática baseada no script do texto. Por padrão, textos em alfabeto latino são interpretados como inglês se o parâmetro language não for fornecido.
Parâmetro language opcional
O campo language aceita códigos ISO para forçar a síntese em um idioma específico, garantindo pronúncia correta mesmo que o script seja ambíguo. É uma opção útil quando o contexto do app exige precisão linguística.
Detecção por script e padrão inglês
Se o parâmetro não for enviado, o sistema infere o idioma pelo conjunto de caracteres. Textos em latim assumem inglês por padrão, o que pode gerar erros de pronúncia em outros idiomas que usam o mesmo alfabeto.
Configuração explícita para latim não inglês
Para idiomas como português, espanhol ou francês, defina o language explicitamente. Isso evita que o motor interprete erroneamente palavras semelhantes ao inglês, garantindo que a voz soe natural para o público-alvo do aplicativo.

Limites e retry
Para apps móveis, a estabilidade da integração depende do respeito aos limites de taxa. A API permite 60 requisições por minuto por chave API, garantindo que o app continue funcional mesmo sob uso moderado. É essencial que os clientes monitorem o cabeçalho X-RateLimit-Remaining para evitar erros 429.
60 requisições por minuto por chave
Cada chave ativa conta como um limite independente. Se o app exceder 60 solicitações em um minuto, as requisições subsequentes retornarão erro. Para apps com alta demanda, considere a rotação de chaves ou o aumento do limite após o primeiro top-up, que sobe para 60 requisições por minuto.
Retries com backoff exponencial
Implemente retries com backoff exponencial para lidar com picos temporários. Um atraso inicial de 500ms, dobrando a cada falha, evita sobrecarregar o servidor novamente. Isso é crucial para manter a fluidez da experiência do usuário, especialmente em conexões móveis instáveis.
- Aguardar 500ms, 1s, 2s antes de reenviar
Monitoramento de fila sob carga
Sob carga, as requisições são processadas em fila. Isso pode aumentar o tempo de resposta para textos longos. Monitore o tempo de geração para ajustar a experiência do usuário, mostrando indicadores de carregamento adequados enquanto o áudio é sintetizado.
Formatos de saída
Escolher o formato correto impacta diretamente o tamanho do arquivo e o consumo de banda em dispositivos móveis. A API oferece mp3, wav, opus, flac e pcm para atender diferentes necessidades de armazenamento e qualidade.
Para a maioria dos casos, mp3 ou opus são recomendados devido ao equilíbrio entre tamanho reduzido e boa fidelidade. O wav é ideal quando a qualidade máxima é prioritária, enquanto o pcm serve para testes técnicos.
mp3 para compatibilidade
O formato mp3 é amplamente suportado por ambos iOS e Android sem necessidade de codecs adicionais. Ele oferece boa compressão, mantendo o tamanho do arquivo pequeno para downloads rápidos em redes móveis.
Use este formato para narrativas padrão ou diálogos em aplicativos, onde o equilíbrio entre qualidade e economia de dados é essencial.
- Ampla compatibilidade nativa
- Compressão eficiente
- Ideal para redes móveis
wav para alta qualidade
O wav entrega áudio sem perda de qualidade, sendo o padrão para produção ou quando a fidelidade sonora é crítica. O arquivo resultante é significativamente maior que o mp3, consumindo mais armazenamento no dispositivo.
Recomendado para apps de áudio profissional ou quando a clareza da voz é o foco principal da experiência do usuário.
- Qualidade sem perda
- Arquivos maiores
- Alta fidelidade
pcm para debugging
O pcm armazena dados de áudio brutos sem compressão, resultando em arquivos grandes e fáceis de analisar programaticamente. É útil para testes de integração ou depuração de pipelines de áudio.
Use pcm quando precisar processar o áudio diretamente ou verificar a integridade dos dados gerados pela API.
- Dados brutos
- Sem compressão
- Útil para testes
Autenticação e chaves
A autenticação na API do SomLeve é baseada em um único token ativo por conta, enviado no cabeçalho HTTP. Qualquer alteração na chave invalida imediatamente a anterior, garantindo controle preciso sobre o acesso.
Essa simplicidade elimina a necessidade de gerenciar múltiplos tokens ou sessões complexas. Basta manter a chave válida no ambiente de produção do app para garantir que as requisições de síntese sejam processadas sem falhas de autorização.
Cabeçalho Authorization Bearer
Envie o token no cabeçalho Authorization: Bearer <sua-chave> em todas as requisições POST para /v1/audio/speech. O formato é padrão OAuth 2.0, compatível com a maioria dos clientes HTTP modernos usados em apps móveis.
Certifique-se de que a chave esteja incluída em cada chamada, pois a ausência do header resulta em erro 401, impedindo a geração do áudio até que a credencial seja fornecida corretamente.
- Use HTTPS para proteger a chave em trânsito.
- Armazene a chave em variáveis de ambiente no app, não hardcoded.
- A chave começa com
tts-para fácil identificação.
Troca de chave invalida a anterior
Ao gerar uma nova chave na página /get-api-key/, a chave antiga deixa de funcionar instantaneamente. Não há período de sobreposição. Isso garante que, em caso de vazamento, o acesso seja revogado imediatamente.
Para testes, isso significa que você deve atualizar a configuração do seu app móvel assim que solicitar uma nova chave, evitando erros de autenticação durante a transição.
Rotação segura de credenciais
A rotação é simples: gere uma nova chave no painel e atualize o app. Como não há histórico de chaves ativas simultâneas, não há risco de uso não autorizado da chave antiga após a troca.
Recomendamos atualizar a chave regularmente ou imediatamente após qualquer suspeita de comprometimento. O processo é manual, via painel web, e não requer downtime da API, apenas a atualização do token no cliente.
Exemplos de erro
Erros de entrada são comuns e geralmente indicam limites técnicos ou de autenticação. Reconhecê-los rapidamente evita desperdício de caracteres e permite ajustes no fluxo de geração.
Texto muito longo
O limite é de 4096 caracteres por requisição. Se o texto exceder esse valor, a API rejeita a solicitação. A solução é dividir o conteúdo em blocos menores e concatenar os áudios resultantes.
- Limite rígido de 4096 caracteres por chamada
- Espaços e pontuação contam como caracteres
- Divisão manual ou automática necessária
Chave expirada ou inválida
A autenticação exige o cabeçalho Authorization: Bearer tts-.... Se a chave estiver incorreta ou revogada, o acesso é negado. Note que emitir uma nova chave invalida a anterior instantaneamente.
- Verifique o prefixo
tts-na chave - Nova chave substitui a anterior imediatamente
- Erro 401 indica autenticação falha
Formato não suportado
Formatos válidos são mp3, wav, opus, flac e pcm. Enviando um tipo inválido, o pedido falha. A escolha do formato impacta diretamente o tamanho do arquivo e o uso de banda no app móvel.
- Suporte a mp3, wav, opus, flac, pcm
- Formatos não listados retornam erro
- Opus oferece melhor compressão para mobile
Monitoramento e logs
O API armazena apenas os metadados necessários para o faturamento: timestamp, contagem de caracteres e status da síntese. O áudio gerado não é retido nos servidores após o envio.
Metadados de tempo e caracteres
Cada requisição registra o momento exato e o volume de texto processado. Esses dados são leves e não incluem o conteúdo da mensagem, preservando a privacidade do input.
Status de sucesso ou falha
O sistema registra se a síntese foi concluída ou falhou. Isso permite que você identifique rapidamente erros de formato ou limites excedidos sem precisar armazenar logs verbose.
Auditoria para faturamento
Os logs de tempo e caracteres são usados exclusivamente para calcular o custo. Como cada milhar de caracteres tem preço fixo, esses dados garantem transparência na cobrança.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Para apps móveis com alto volume, considere o uso de múltiplas chaves ou implemente lógica de retry com backoff exponencial.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
