Integração e Uso da API de Síntese de Voz

Por Equ editorial SomLeve · Atualizado 2026-11-19

Esta documentação técnica detalha a integração da API SomLeve para síntese de voz em aplicativos móveis. Aqui você encontra os parâmetros exatos para enviar texto e receber áudio, a estrutura de autenticação e os limites de uso da API de texto para fala.

O guia é projetado para times de produto que precisam de dados claros e integração previsível. Utilizamos o padrão OpenAI, permitindo que você altere apenas o base_url para começar. Veja como configurar vozes, formatos e velocidade para sua aplicação.

Integração e Uso da API de Síntese de Voz

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.mp3

Python (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
ariafeminino
novafeminino
lunafeminino
sagefeminino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Autenticação

Ilustração de onda sonora para: 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

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

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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

Parâmetros adicionais

SDK OpenAI e base_url

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

Avatar da voz aria
ariafeminino
Avatar da voz nova
novafeminino
Avatar da voz luna
lunafeminino
Avatar da voz sage
sagefeminino
Avatar da voz felix
felixmasculino
Avatar da voz milo
milomasculino
Avatar da voz atlas
atlasmasculino
Avatar da voz orion
orionmasculino

23 idiomas

Qualquer voz fala qualquer um desses idiomas.

Fontes e leituras adicionais

  1. Wikipedia
  2. MDN: Web Speech API
  3. TRON developer hub: TRC-20
  4. W3C WAI: making audio and video accessible
  5. OpenAI API reference: create speech
  6. ISO 639 language codes
  7. Node.js documentation
  8. IETF RFC 7845: Ogg Opus
  9. curl documentation
  10. FFmpeg documentation
  11. Python documentation
  12. LibriTTS-R corpus (OpenSLR 141)

Mais neste site