Perguntas frequentes
Como obter minha chave API?
Acesse /get-api-key/ e registre-se com Google ou e-mail e senha. A página exibe sua chave ativa, saldo e um exemplo de curl. Cada conta possui uma única chave ativa; você pode emitir uma nova a qualquer momento, invalidando a anterior imediatamente.
Qual o formato da requisição JSON?
Envie um POST para /v1/audio/speech com o corpo JSON contendo: model ("tts-1" ou "tts-1-hd"), input (texto, até 4096 caracteres), voice (um dos 8 presets), response_format (mp3, wav, opus, flac, pcm), speed (0.25–4.0) e language (opcional). A autenticação usa o cabeçalho Authorization: Bearer sua-chave.
Posso usar o SDK oficial da OpenAI?
Sim. Como a forma da requisição é idêntica à da OpenAI, você pode utilizar os SDKs oficiais deles. Basta alterar a base_url para https://api.air123.cc/v1 e usar sua chave de API SomLeve para autenticar as solicitações de síntese de voz.
Como alterar a base_url do SDK?
Configure a propriedade base_url do seu cliente SDK para https://api.air123.cc/v1. Isso redireciona as chamadas para a nossa API em vez da OpenAI. Mantenha o restante da lógica e o formato do corpo JSON iguais aos exemplos padrão do SDK.
Quais formatos de áudio estão disponíveis?
Você pode solicitar áudio nos formatos mp3, wav, opus, flac ou pcm. Escolha o response_format adequado ao seu pipeline de áudio. O formato pcm gera áudio bruto, enquanto opus e flac oferecem compressão eficiente sem perda ou com perda controlada.
O que é tts-1-hd?
tts-1-hd é um dos dois modelos disponíveis, compartilhando o mesmo motor e preço do tts-1. Ambos custam US$ 10 por milhão de caracteres. A escolha entre eles não altera o custo nem a qualidade percebida, pois utilizam o mesmo motor.
Como definir a velocidade da voz?
Use o campo speed na requisição, aceitando valores entre 0.25 e 4.0. O padrão é 1.0. Valores menores retardam a fala, enquanto valores maiores a aceleram. Isso permite ajustar o ritmo do áudio gerado para melhor adequação ao contexto do seu aplicativo.
Posso definir o idioma explicitamente?
Sim, use o campo language com um código ISO. Se não definido, o idioma é adivinhado pelo script (texto latino assume inglês). Para textos em latim fora do inglês, defina language explicitamente. Os 23 idiomas suportados incluem português, espanhol, francês e japonês.
Qual o limite de caracteres por pedido?
Cada requisição aceita até 4096 caracteres no campo input. Textos maiores devem ser divididos em partes de até esse limite. Você deve juntar os arquivos de áudio resultantes para criar o áudio final completo, pois cada pedido gera um arquivo independente.
O que acontece ao exceder 60 requisições/min?
O limite é de 60 requisições por minuto por chave. Antes do primeiro recarga, o limite é de 10 por minuto. Se exceder, as requisições podem ser recusadas ou processadas em fila. O processamento é sequencial, então solicitações sob carga podem aguardar.
As requisições falhas são cobradas?
Não. Se a síntese falhar, o valor é devolvido integralmente ao seu saldo. Apenas as requisições bem-sucedidas são cobradas. O metadata de tempo, caracteres e status é mantido para fins de faturamento, mas o custo do áudio falho é zero.
Como listar vozes e idiomas disponíveis?
Faça uma requisição GET para /v1/voices. Esse endpoint retorna a lista de vozes, idiomas, formatos suportados e preços. Você também pode acessar /v1/models para informações sobre os modelos disponíveis. Use essas informações para validar as configurações antes de enviar áudio.
Existe endpoint para modelos?
Sim, acesse GET /v1/models. Ele fornece detalhes sobre os modelos disponíveis, como tts-1 e tts-1-hd. Use este endpoint para verificar as especificações técnicas e confirmar quais modelos estão ativos e disponíveis para uso na sua conta SomLeve.
Como rastrear erros na resposta?
A API retorna códigos de status HTTP padrão e mensagens de erro no corpo da resposta JSON. Verifique o status code para identificar falhas específicas, como limites excedidos ou parâmetros inválidos. As falhas de síntese resultam em reembolso automático e sem cobrança.
Primeira solicitação
curl
curl https://api.air123.cc/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.air123.cc/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.air123.cc/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
Para acessar a API, inclua o cabeçalho Authorization: Bearer com sua chave única no corpo da requisição HTTP. Cada conta mantém apenas uma chave ativa por vez, simplificando a gestão de segurança sem necessidade de rotacionar múltiplos tokens simultaneamente.
A emissão de uma nova chave invalida imediatamente a anterior, garantindo que apenas o token mais recente tenha acesso aos recursos de síntese de voz.
Cabeçalho Authorization Bearer
Utilize o formato Authorization: Bearer <sua-chave> em todas as requisições POST para /v1/audio/speech. Certifique-se de que a chave esteja corretamente codificada no cabeçalho HTTP padrão.
A autenticação é baseada em token Bearer, compatível com a estrutura utilizada pelos SDKs oficiais da OpenAI ao ajustar o base_url.
- Formato:
Authorization: Bearer tts-... - Requerido em todas as requisições
- Compatível com HTTP padrão
Uma chave ativa por conta
Cada conta possui uma única chave de API ativa. Isso evita conflitos de permissão e simplifica o rastreamento de uso e limites de taxa por cliente.
A chave é gerada durante o cadastro ou na área de gerenciamento da conta, onde também é possível visualizar o saldo e o histórico de caracteres.
- Apenas uma chave válida por conta
- Geração na página de gerenciamento
- Rastreamento unificado de uso
Troca de chave invalida a anterior
Ao solicitar uma nova chave, a chave anterior deixa de funcionar instantaneamente. Não há período de transição ou sobreposição.
Essa característica garante segurança imediata em caso de exposição acidental da chave antiga, sem necessidade de esperar expiração manual.
- Invalidação instantânea
- Sem período de sobreposição
- Requer atualização no código cliente
Endpoint principal
A síntese de voz ocorre via requisição POST para o endpoint /v1/audio/speech. O serviço recebe texto bruto e retorna um arquivo de áudio processado, seguindo o formato padrão de APIs de speech.
POST /v1/audio/speech
Envie a requisição para o endereço https://api.air123.cc/v1/audio/speech. O corpo deve conter o modelo selecionado e o texto a ser convertido.
Corpo JSON com modelo e input
O payload JSON deve incluir o campo model ("tts-1" ou "tts-1-hd") e o input com o texto. O texto suportado tem limite de 4096 caracteres por requisição.
Retorno com arquivo de áudio
A resposta contém o arquivo de áudio no formato solicitado (response_format). O arquivo é entregue diretamente no corpo da resposta HTTP para download imediato no app.
Modelos e vozes
A API oferece dois modelos de motor, tts-1 e tts-1-hd, que compartilham o mesmo motor e o mesmo preço de $0,01 por mil caracteres. A escolha entre eles é puramente técnica, sem impacto na fatura ou na latência percebida pelo usuário final.
O sistema conta com oito vozes pré-definidas, divididas entre masculinas e femininas, capazes de falar em 23 idiomas. Cada voz possui uma característica timbrada específica, desde narrativas quentes até vozes neutras para notícias, permitindo que equipes de produto ajustem o tom da aplicação sem depender de clonagem personalizada.
tts-1 e tts-1-hd mesmo preço
Ambos os modelos utilizam o mesmo engine de síntese e têm custo idêntico. A distinção reside na configuração interna do motor, mas para fins de integração e cobrança, eles são intercambiáveis. Recomendamos o uso do modelo que melhor se integra à sua implementação existente, mantendo a previsibilidade de custos.
8 vozes disponíveis
As vozes são baseadas em gravações licenciadas (LibriTTS-R e LibriVox), garantindo clareza e naturalidade. Não há tags de emoção ou SSML; a entonação é determinada pelo perfil da voz selecionada. Exemplos incluem Aria (narradora clara), Felix (energia promocional) e Atlas (neutralidade jornalística).
Cada arquivo gerado contém uma marca d'água inaudível que identifica o áudio como síntese artificial, importante para transparência em apps móveis que utilizam voz assistida ou audiodescrição.
- Aria (F): Narradora quente e clara
- Nova (F): Voz brilhante e animada
- Luna (F): Suave, ideal para storytelling
- Sage (F): Calma, instrucional
- Felix (M): Energética, promo
- Milo (M): Amigável, conversacional
- Atlas (M): Neutra, notícias
- Orion (M): Profunda, documentário
Listagem via GET /v1/voices
Para obter a lista completa e atualizada das vozes, idiomas e formatos disponíveis, utilize o endpoint GET /v1/voices. Esta rota retorna o JSON com os IDs válidos para o parâmetro voice nas requisições de síntese.
Recomendamos consultar este endpoint durante o desenvolvimento para garantir que a voz selecionada suporte o idioma definido no parâmetro language, evitando falhas de síntese silenciosa ou defaults incorretos.
Formatos de saída
O formato PCM retorna os dados de áudio brutos, sem cabeçalhos de container. Isso é útil para debug ou quando você precisa processar o fluxo de bytes diretamente.
mp3, wav, opus, flac, pcm
Você pode solicitar o áudio em cinco formatos distintos: mp3, wav, opus, flac ou pcm. A escolha afeta diretamente o tamanho do arquivo e a compatibilidade com seu player de áudio nativo ou biblioteca de reprodução no app móvel.
Para a maioria dos casos de uso em produção, o mp3 oferece o melhor equilíbrio entre qualidade auditiva e eficiência de rede. O wav preserva a qualidade lossless sem compressão, enquanto o opus e o flac são opções válidas dependendo da necessidade específica de armazenamento ou streaming.
- mp3: compressão com perda, ideal para redução de dados
- wav: áudio sem compressão, alta fidelidade
- opus: eficiente para streaming em redes instáveis
- flac: compressão sem perda de qualidade
- pcm: dados brutos sem cabeçalhos
mp3 recomendado para mobile
Para aplicativos móveis, o mp3 é a escolha padrão devido ao seu amplo suporte nativo e tamanho reduzido. Isso ajuda a economizar banda do usuário e espaço de armazenamento no dispositivo, mantendo uma experiência de áudio fluida sem overhead desnecessário.
pcm para debug e streaming raw
O formato pcm retorna os dados de áudio brutos, sem cabeçalhos de container. Isso é útil para debug ou quando você precisa processar o fluxo de bytes diretamente. Use este formato apenas se precisar processar o fluxo de bytes diretamente ou testar latências de decodificação.
Parâmetros adicionais
Além dos parâmetros obrigatórios, a API oferece controle fino sobre a entrega do áudio. A velocidade de reprodução pode ser ajustada para adaptar o conteúdo às necessidades do usuário final, sem alterar a voz base.
O idioma é opcional mas recomendado. Se não especificado, o sistema tenta adivinhar com base no script, assumindo inglês para texto em latim. Para línguas como português ou espanhol, definir o código ISO garante a pronúncia correta.
Velocidade de 0.25 a 4.0
Ajuste a velocidade entre 0.25x e 4.0x para acelerar leituras rápidas ou desacelerar para clareza. O valor padrão mantém o ritmo natural da voz selecionada.
Idioma opcional por código ISO
Defina o parâmetro language com o código ISO (ex: pt-BR, es-ES) para garantir a pronúncia correta. Isso evita que o texto em português seja lido com sotaque inglês.
Todas as 8 vozes suportam os 23 idiomas listados. A ausência do campo força o palpite do sistema, o que pode resultar em erros de pronúncia em textos mistos.
Texto máximo de 4096 caracteres
Cada requisição suporta até 4096 caracteres, incluindo espaços e pontuação. Para textos longos, divida o conteúdo em partes e junte os arquivos de áudio resultantes.
O limite é por chamada API. Textos excedentes devem ser fragmentados na lógica do cliente antes do envio.

SDK OpenAI e base_url
Alterar base_url para api.site-domain
Configure a variável de ambiente ou parâmetro de conexão da biblioteca para apontar para https://api.air123.cc/v1. Essa mudança redireciona todas as chamadas de síntese para a infraestrutura do SomLeve, mantendo a estrutura padrão exigida pelo protocolo.
Não é necessário alterar os métodos de envio ou a estrutura dos payloads. A configuração isolada da URL base garante que o SDK se comunique exclusivamente com o endpoint de texto para fala desta plataforma.
Mesma forma de requisição OpenAI
A estrutura do corpo JSON permanece idêntica ao padrão usado para geração de áudio. Utilize os campos model, input, voice e response_format exatamente como documentado no endpoint principal. O formato da resposta também segue o padrão binário ou JSON esperado.
SDKs oficiais compatíveis
Os SDKs oficiais da OpenAI funcionam nativamente ao ponto da mudança de base_url. Isso permite integrar a síntese de voz no código existente de apps móveis sem criar uma camada de abstração personalizada ou importar bibliotecas adicionais.
- SDKs oficiais da OpenAI
Limites e filas
A API impõe limites claros de taxa para garantir estabilidade. Cada chave de API aceita até 60 requisições por minuto após a configuração inicial da conta.
60 requisições por minuto
O limite padrão permite processamento contínuo de textos curtos e médias chamadas de síntese. Se o volume ultrapassar 60 solicitações em um minuto, as requisições extras receberão erro de limite excedido.
10 por minuto antes do primeiro top-up
Contas novas, sem crédito recarregado, têm uma janela mais restrita de 10 requisições por minuto. Isso previne consumo acidental da avaliação gratuita ($0,50) em testes intensivos. O limite sobe para 60 rpm imediatamente após o primeiro depósito via USDT.
Processamento em fila sob carga
Quando há muitas solicitações simultâneas, elas são processadas sequencialmente. Textos longos podem esperar na fila até que as sínteses anteriores sejam concluídas. Isso significa que o tempo de resposta pode variar dependendo do volume de tráfego no momento.
Erros comuns
Erros de integração geralmente surgem de expectativas não alinhadas com o limite de caracteres ou com a validade da chave. Verificar a assinatura e o tamanho do payload antes do envio evita interrupções no fluxo de áudio.
Texto excede 4096 caracteres
Cada requisição aceita no máximo 4096 caracteres, incluindo espaços e pontuação. O texto muito longo deve ser dividido em partes menores pelo cliente e os arquivos resultantes unidos posteriormente.
Chave ausente ou inválida
A autenticação exige o cabeçalho Authorization: Bearer tts-.... Uma chave revogada ou incorreta retorna erro imediato. Lembre-se que emitir uma nova chave invalida a anterior instantaneamente.
Formato não suportado
Apenas mp3, wav, opus, flac e pcm são aceitos. Solicitar um formato não listado resulta em falha na síntese, sem 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.
