Perguntas frequentes
O que é uma API de TTS para IoT?
É um serviço em nuvem que converte texto em arquivos de áudio via endpoint POST. Ideal para notificações e assistentes em hardwares embarcados, enviando texto e recebendo o arquivo de áudio com latência previsível e custos escaláveis para equipes de produto IoT.
Como a API processa textos longos?
O texto deve ser dividido em partes de até 4096 caracteres. Cada parte gera um arquivo de áudio separado, que são unidos para formar o áudio final. Isso garante que textos extensos sejam processados sem ultrapassar os limites da API.
Qual a latência média de geração?
Textos longos geram áudio em tempo real aproximado (25 caracteres por segundo). Frases curtas levam alguns segundos. Sob carga, as requisições podem aguardar na fila, pois são processadas sequencialmente. A latência depende do volume de requisições simultâneas.
A API funciona em dispositivos offline?
Não. A API é baseada em nuvem. O dispositivo precisa enviar o texto via HTTP POST para o endpoint e receber o áudio de volta. Conectividade com a internet é obrigatória para o processamento e entrega do arquivo de áudio.
Quais formatos de áudio são mais leves?
Os formatos disponíveis são mp3, wav, opus, flac e pcm. Para IoT, mp3 e opus são geralmente mais leves e eficientes em largura de banda. O formato pcm é não comprimido, enquanto wav é maior. Escolha conforme sua necessidade de qualidade vs. tamanho.
Como lidar com falhas de conexão?
Se a síntese falhar, o valor é devolvido integralmente. Implemente lógica de retry no seu código. Como as requisições são processadas uma após a outra, falhas podem causar atrasos. Monitore o status da resposta e reenvie o texto se necessário, respeitando os limites de taxa.
A voz muda dependendo do idioma?
As 8 vozes são pré-definidas e podem falar qualquer um dos 23 idiomas suportados. A voz não muda de timbre, mas a pronúncia se adapta ao idioma especificado ou detectado. Defina o parâmetro 'language' para garantir a pronúncia correta, especialmente para textos em latim não ingleses.
Posso controlar a velocidade da voz?
Sim. O parâmetro speed aceita valores entre 0.25 e 4.0. Isso permite ajustar a velocidade da fala para notificações rápidas ou instruções detalhadas em dispositivos IoT. A qualidade da síntese é mantida, mas o tempo de geração varia conforme a configuração, processando as requisições em sequência para garantir a consistência do áudio entregue ao hardware embarcado.
O que é a taxa de 60 requests por minuto?
É o limite de taxa (rate limit) por chave de API. Após o primeiro recarga, você pode fazer 60 requisições por minuto. Antes disso, o limite é de 10 por minuto. Exceder esse limite pode resultar em erros ou espera na fila de processamento.
A API cobra por segundo de áudio?
Não. A cobrança é baseada em caracteres: $10 por 1 milhão de caracteres (ou $0,01 por 1.000 caracteres). Espaços e pontuação contam. O tempo de geração não influencia o custo, apenas a quantidade de texto enviado na requisição.
Como funciona a detecção de idioma?
Se o parâmetro 'language' não for definido, o sistema tenta adivinhar pelo script. Textos em latino padrão para inglês. Para outros idiomas em latim, defina explicitamente o código ISO para evitar erros de pronúncia. Idiomas não suportados não serão processados corretamente.
Posso usar vozes masculinas e femininas?
Sim. Existem 8 vozes pré-definidas: 4 femininas (Aria, Nova, Luna, Sage) e 4 masculinas (Felix, Milo, Atlas, Orion). Cada uma tem um tom distinto, como narrador, energético ou neutro. Selecione a voz adequada ao contexto da sua aplicação IoT via parâmetro 'voice'.
O áudio gerado é armazenado na nuvem?
Não. O áudio é retornado diretamente na resposta da API e não é armazenado. Apenas os metadados da requisição (tempo, caracteres, status) são mantidos para fins de cobrança. O texto de entrada é usado apenas para gerar o áudio e não para treinamento.
A API suporta acentos e pontuação?
Sim. A síntese de voz processa acentos e pontuação como parte dos caracteres enviados. Todos os caracteres, incluindo espaços e sinais de pontuação, contam para a cobrança por caractere.
Como funciona o watermark no áudio?
Cada arquivo de áudio gerado contém uma marca d'água inaudível que identifica o conteúdo como fala sintética. Isso é aplicado automaticamente em todos os arquivos gerados pela API, permitindo a identificação do áudio como gerado por IA, sem afetar a escuta humana.
Preciso de internet para usar a API?
Sim. Como a API é baseada em nuvem, seu dispositivo IoT precisa de conexão com a internet para enviar o texto e receber o arquivo de áudio. Não há SDK offline ou processamento local mencionado. A latência depende da sua conexão e da fila da API.
A API funciona em Raspberry Pi?
Sim. Como a API é acessível via HTTP POST padrão, qualquer dispositivo com conexão à internet e capacidade de executar requisições HTTP pode usá-la, incluindo Raspberry Pi. Basta enviar o JSON com os parâmetros necessários e processar a resposta de áudio.
Existe limite de uso contínuo?
Não há limite de uso contínuo, apenas o limite de taxa de 60 requisições por minuto por chave. O saldo não expira e você pode usar a API continuamente desde que tenha crédito. Falhas são gratuitas e não consomem saldo.
O fluxo de geração de áudio
A integração começa com uma requisição HTTP POST para o endpoint /v1/audio/speech. O corpo da solicitação contém o texto a ser sintetizado, o modelo selecionado ("tts-1" ou "tts-1-hd") e as configurações de voz e idioma, seguindo o formato JSON padrão compatível com SDKs OpenAI.
O texto é limitado a 4096 caracteres por requisição. Para textos maiores, é necessário dividir a entrada em partes menores e concatenar os arquivos de áudio resultantes posteriormente. A autenticação é feita via token Bearer no cabeçalho da requisição.
Envio do texto via JSON
O cliente IoT envia o payload JSON contendo o campo input com o texto, voice para a preseta desejada e model. É possível definir response_format (mp3, wav, opus, flac, pcm) e ajustar a speed entre 0.25 e 4.0.
O idioma pode ser especificado via código ISO ou inferido automaticamente. Para textos em latinos não-ingleses, recomenda-se definir o parâmetro language explicitamente para evitar detecção incorreta como inglês.
- Endpoint: POST /v1/audio/speech
- Campos: model, input, voice, response_format, speed
- Autenticação: Authorization: Bearer <chave>
Processamento sequencial na nuvem
As requisições são processadas em fila, uma após a outra. Isso significa que, sob alta carga, pode haver espera antes do início da síntese. A velocidade média é de aproximadamente 25 caracteres por segundo de áudio gerado.
Textos longos levam mais tempo devido ao processamento sequencial. Frases curtas são geradas rapidamente, mas ainda demandam alguns segundos para inicialização e conclusão.
Retorno do arquivo binário
A resposta contém o arquivo de áudio binário no formato solicitado. Não há streaming; o arquivo completo é retornado apenas após a conclusão da síntese.
O arquivo não é armazenado permanentemente pelo serviço; ele é retornado apenas na resposta da requisição. O dispositivo IoT deve receber e processar o áudio imediatamente ou armazená-lo localmente se necessário.
Latência e Tempo de Resposta
A síntese opera em tempo real aproximado, processando cerca de 25 caracteres por segundo de áudio gerado. Esse ritmo linear permite previsibilidade no fluxo de dados para dispositivos IoT que dependem de áudio contínuo sem lacunas perceptíveis, desde que o texto seja dividido em partes menores.
Velocidade próxima da tempo real
A geração de áudio segue um ritmo constante, facilitando o sincronismo em notificações de smart home. Para textos longos, o processamento mantém essa taxa, mas o dispositivo recebe arquivos separados que devem ser concatenados, o que pode introduzir latência adicional.
- Taxa média de 25 caracteres gerados por segundo
- Processamento linear para textos extensos
Impacto da fila de processamento
As requisições são processadas sequencialmente, o que significa que, sob carga, uma solicitação pode aguardar na fila. Isso introduz latência variável, crítica para sistemas de controle instantâneo onde milissegundos importam.
Diferença entre frases curtas e longas
Frases curtas exigem alguns segundos fixos para inicialização e síntese, independentemente do tamanho do texto. Já textos longos seguem a taxa de tempo real, mas acumulam tempo total de processamento devido à natureza sequencial da fila.
Gerenciamento de texto longo
O limite de 4096 caracteres por requisição exige planejamento de buffer em dispositivos com memória restrita. Textos superiores a esse tamanho devem ser segmentados antes do envio para evitar falhas na síntese.
A divisão manual é necessária para controlar a semântica das frases geradas. O cliente deve garantir que cada parte respeite o limite, evitando cortes abruptos que prejudiquem a compreensão da mensagem no dispositivo IoT.
Limite de 4096 caracteres
Cada chamada POST aceita no máximo 4096 caracteres, incluindo espaços e pontuação. Exceder esse limite resulta em erro na requisição, interrompendo o fluxo de geração de áudio imediato.
Divisão manual
A API não realiza divisão automática. É responsabilidade do sistema embarcado ou do servidor backend segmentar o texto. A lógica de corte deve considerar pontos finais ou vírgulas para manter a coerência da fala sintetizada.
Juntar arquivos de áudio gerados
Após receber os arquivos de áudio individuais de cada segmentação, o dispositivo deve concatená-los. Isso pode ser feito via buffering de memória ou escrita sequencial em arquivo temporário antes da reprodução.
Garanta que a ordem das requisições seja preservada. Como as solicitações são processadas sequencialmente sob carga, a latência pode variar, mas a ordem de chegada dos arquivos deve ser mantida para a reprodução contínua.
Seleção de voz e idioma
A escolha da voz influencia diretamente a experiência do usuário final em dispositivos IoT. O sistema oferece oito vozes predefinidas, divididas entre masculinas e femininas, cada uma com um timbre específico para diferentes contextos de uso.
O idioma pode ser detectado automaticamente ou forçado via parâmetro. Isso garante que a síntese seja precisa, mesmo quando o texto contém caracteres latinos mas não é em inglês.
8 vozes predefinidas disponíveis
O catálogo inclui vozes como Aria (narradora clara), Nova (animada), Luna (suave), Sage (instrucional), Felix (energético), Milo (conversacional), Atlas (neutra) e Orion (documentário). Cada voz é baseada em gravações licenciadas e pode ser selecionada pelo parâmetro voice na requisição.
Essas vozes são adequadas para notificações de smart home, assistentes de voz e feedback auditivo de dispositivos embarcados.
- Femininas: aria, nova, luna, sage
- Masculinas: felix, milo, atlas, orion
- Baseadas em gravações licenciadas (LibriTTS-R)
- Cada voz pode falar qualquer um dos 23 idiomas suportados
Detecção automática de script
Se o parâmetro language não for definido, o sistema tenta inferir o idioma com base no script do texto. Para textos em caracteres latinos, o padrão é o inglês.
Essa detecção funciona bem para textos simples, mas pode falhar em casos ambíguos ou multilingues.
Forçar idioma via parâmetro
Para garantir precisão, defina explicitamente o parâmetro language com o código ISO do idioma desejado (ex: pt, es, de). Isso evita erros de pronúncia em textos não-ingleses em script latino.
Isso é especialmente útil em dispositivos IoT que podem receber comandos ou notificações em diferentes idiomas.
- Códigos ISO suportados: ar, zh, da, nl, en, fi, fr, de, el, he, hi, it, ja, ko, ms, no, pl, pt, ru, es, sw, sv, tr
- Recomendado para textos em português, espanhol, alemão, etc., mesmo que em script latino
Formatos ideais para hardware
A escolha do formato de áudio impacta diretamente o consumo de CPU e memória nos dispositivos embarcados de smart home. Cada codec exige diferentes capacidades de decodificação no hardware, influenciando a experiência do usuário final em notificações e assistentes de voz.
O formato deve equilibrar qualidade, latência e complexidade de processamento, garantindo que o dispositivo responda com a latência previsível esperada para feedback auditivo imediato.
MP3 para dispositivos básicos
O MP3 é amplamente suportado pela maioria dos chips de áudio embedded, exigindo pouco poder de processamento para decodificação. É ideal para notificações simples onde a qualidade de áudio é secundária ao consumo de energia.
A compressão reduz significativamente o tamanho do arquivo, facilitando o armazenamento em dispositivos com memória limitada.
- Ampla compatibilidade com hardware legacy
- Baixo consumo de CPU durante reprodução
- Tamanho de arquivo reduzido
PCM para processamento direto
O PCM oferece áudio bruto não comprimido, eliminando a necessidade de decodificação antes da reprodução. Isso reduz a latência, sendo ideal para respostas de voz rápidas que exigem interação imediata.
O trade-off é o maior consumo de banda e armazenamento, mas o processamento do dispositivo é mínimo.
- Latência mínima de reprodução
- Sem complexidade de decodificação
- Maior uso de banda e armazenamento
OPUS para largura de banda baixa
O OPUS oferece excelente compressão com boa qualidade, sendo eficiente para dispositivos que operam em redes com limitações de largura de banda. Ideal para transmissão de áudio via Wi-Fi ou redes IoT de baixo consumo.
Permite manter a qualidade da voz em condições de rede variáveis, comum em ambientes domésticos com muitos dispositivos conectados.
- Alta eficiência de compressão
- Adaptável a redes instáveis
- Qualidade mantida em baixa taxa de bits
Custos operacionais por geração
A cobrança é estritamente proporcional ao volume de texto processado, custando $0,01 por cada 1.000 caracteres, incluindo espaços e pontuação. Esse modelo linear facilita o cálculo exato do custo operacional para notificações de smart home, independentemente da complexidade do conteúdo.
A velocidade de reprodução (0,25x a 4,0x) não altera o preço, mas impacta a latência percebida pelo usuário final e o tempo de geração na nuvem.
Cobrança por caractere processado
Cada caractere enviado no campo input conta para a fatura. Textos longos são divididos em partes de até 4096 caracteres, e o custo total é a soma das partes processadas com sucesso.
Requisições que falham durante a síntese não geram cobrança, devolvendo o crédito integralmente. Isso protege o orçamento em cenários de instabilidade na conexão do dispositivo IoT.
- Preço fixo: $10 por 1 milhão de caracteres
- Espaços e pontuação contam como caracteres
- Falhas de síntese são gratuitas
Efeito da velocidade na geração
Ajustar a velocidade (parâmetro speed) modifica a duração do áudio, mas não o custo por caractere. Textos gerados em velocidade acelerada podem parecer mais rápidos, mas o processamento na nuvem segue um tempo base.
Velocidades extremas (0,25 ou 4,0) podem afetar a clareza em dispositivos com alto-falantes de baixa qualidade, exigindo teste de usabilidade antes da implantação em larga escala.
Otimização de tamanho de áudio
A escolha do response_format impacta diretamente o armazenamento local e a largura de banda. Formatos como MP3 e OPUS reduzem o tamanho do arquivo final, ideal para dispositivos com memória limitada.
PCM oferece qualidade bruta sem compressão, resultando em arquivos maiores, enquanto FLAC oferece compressão sem perda. A seleção deve equilibrar a fidelidade necessária para o feedback auditivo com a eficiência de rede.
- MP3/OPUS: menor tamanho de arquivo
- PCM: sem compressão, maior tamanho
- FLAC: compressão sem perda de qualidade
Integração com sistemas embarcados
A integração com sistemas embarcados é direta, utilizando HTTP POST para enviar texto e receber áudio. O endpoint aceita JSON com parâmetros como model, input e voice, retornando o arquivo binário instantaneamente.
A autenticação ocorre via header Authorization: Bearer com a chave única da conta. Isso garante que cada dispositivo ou serviço envie requisições identificadas, permitindo o controle preciso de limites de taxa e custos.
Uso de HTTP POST simples
Dispositivos IoT enviam requisições POST para /v1/audio/speech com o corpo JSON contendo o texto e as configurações de voz. A estrutura é compatível com a API de fala do OpenAI, facilitando o uso de SDKs existentes com ajuste de base_url.
- Endpoint: POST https://api.spinlygame.com/v1/audio/speech
- Corpo: JSON com
input,voice,model - Resposta: arquivo de áudio binário direto
Autenticação com token Bearer
Cada chave API ativa um único token válido. Ao gerar uma nova chave, a anterior é invalidada imediatamente, simplificando a gestão de segurança em dispositivos distribuídos sem necessidade de renovação complexa de certificados.
- Header:
Authorization: Bearer tts-... - Uma chave ativa por conta
- Invalidação instantânea ao regenerar
Parsing de resposta JSON
A resposta contém o arquivo de áudio no formato solicitado (mp3, wav, opus, etc.). Não há necessidade de parsing complexo de metadados, pois o corpo da resposta é o arquivo binário pronto para reprodução ou armazenamento temporário.
- Formatos suportados: mp3, wav, opus, flac, pcm
- Resposta direta: arquivo binário
- Sem estrutura JSON aninhada

Tratamento de falhas na rede
Em ambientes IoT, a instabilidade da rede é comum. O tratamento de falhas na API TTS exige estratégias de retentativa e monitoramento rigoroso para garantir que as notificações sonoras sejam entregues sem bloquear o dispositivo principal.
Retentativa em caso de timeout
Implemente retentativas exponenciais simples para erros de conexão. Como os pedidos são processados em fila, aguardar alguns segundos antes de reenviar o JSON evita sobrecarregar o endpoint e melhora a taxa de sucesso.
- Use backoff exponencial entre reenvios
- Limite o número máximo de tentativas
Verificação de status HTTP
Verifique sempre o status da resposta antes de processar o áudio binário. Códigos 4xx indicam erro no token ou formato, enquanto 5xx sugerem sobrecarga temporária no serviço de síntese.
Consumo de crédito em falhas
O crédito só é consumido se a síntese for bem-sucedida. Se a geração falhar, a cobrança é revertida integralmente, protegendo seu saldo em casos de instabilidade momentânea do serviço.
Qualidade de áudio em dispositivos pequenos
Dispositivos IoT com recursos limitados exigem equilíbrio entre fidelidade sonora e consumo de memória. A API oferece formatos como MP3 e OPUS, ideais para compressão eficiente sem perda crítica de inteligibilidade, enquanto PCM bruto garante processamento imediato em hardware com baixo overhead de decodificação.
Balanceamento entre qualidade e tamanho
Escolher o formato certo impacta diretamente a latência de reprodução e o uso de RAM no dispositivo final. Formatos comprimidos reduzem o tamanho do payload transferido pela rede, permitindo atualizações mais rápidas de notificações de voz em smart home.
Uso de codecs leves
O suporte a OPUS e MP3 permite decodificação acelerada em microcontroladores modernos. Já o formato PCM, embora maior, elimina a necessidade de bibliotecas de decodificação complexas, sendo ideal para dispositivos que priorizam simplicidade de firmware sobre economia de banda.
Experiência do usuário final
A clareza da voz sintetizada é mantida mesmo em compressões agressivas, garantindo que instruções de assistentes ou alertas de sensores sejam compreendidos imediatamente. O áudio gerado é efêmero, focando na entrega imediata da informação auditiva sem acumulação de dados no dispositivo.
Escalabilidade em grande escala
O limite de 60 requisições por minuto por chave exige estratégias de escalonamento para dispositivos IoT em grande escala. Com apenas 10 requisições por minuto antes do primeiro recarga, equipes de produto devem distribuir a carga entre múltiplas chaves API para evitar gargalos em notificações simultâneas.
Gestão de múltiplas chaves API
Cada conta permite uma chave ativa por vez, mas novas chaves podem ser emitidas a qualquer momento, invalidando a anterior instantaneamente. Para alta escala, emita múltiplas chaves e distribua-as entre grupos de dispositivos ou microsserviços, garantindo que o limite de 60 req/min seja respeitado por instância.
- Emita novas chaves para expandir capacidade; note que a chave anterior é invalidada imediatamente.
- Limite: 60 req/min por chave (10 req/min inicial).
Monitoramento de taxa de uso
Monitore o consumo de caracteres e o status das requisições para prever a necessidade de novas chaves. Como as requisições são processadas em fila, picos de geração podem aumentar a latência. Use os metadados de uso para ajustar a frequência de notificações ou dividir textos longos antes do envio.
- Rastreie caracteres processados para estimar custos e limites.
- Monitore filas para evitar timeouts em picos de uso.
Distribuição de carga entre regiões
A API é baseada em nuvem única, mas a distribuição de chaves permite simular uma arquitetura distribuída. Atribua chaves específicas a diferentes regiões ou clusters de dispositivos IoT. Isso isola falhas e garante que o limite de taxa de uma região não afete outras operações globais.
- Atribua chaves por região ou cluster de dispositivos.
- Isole limites de taxa para isolar falhas.
Privacidade de dados no dispositivo
Na arquitetura típica de IoT, o dispositivo atua como cliente da API. O texto a ser sintetizado é enviado via HTTP POST e o áudio retorna imediatamente. Uma vez processado, o texto original não é persistido no hardware do dispositivo, garantindo que informações sensíveis de notificação ou comandos de voz não permaneçam na memória do aparelho após a execução.
Texto não fica armazenado no device
O fluxo é stateless: o dispositivo envia o input e recebe o audio. Não há cache local do texto processado, o que reduz o uso de memória flash e previne vazamento de dados por arquivos órfãos.
- Envio único via POST
- Sem persistência local do input
Áudio gerado é efêmero
O arquivo de áudio é devolvido na resposta HTTP e não é armazenado pelos nossos servidores após a entrega. Ele pode ser reproduzido e descartado pelo firmware do dispositivo, deixando apenas os metadados de billing.
- Audio retornado na resposta
- Sem armazenamento server-side
Metadados de uso retidos
Para fins de cobrança e auditoria, mantemos registros do timestamp, quantidade de caracteres processados e status da requisição. Esses dados são mínimos e não incluem o conteúdo do texto ou do áudio em si.
- Timestamp e status
- Volume de caracteres
Manutenção e Atualizações da API
A API não oferece contrato de nível de serviço (SLA) nem garantia de tempo de atividade (uptime). Isso significa que não há compensação financeira ou penalidades contratuais em caso de indisponibilidade inesperada.
A infraestrutura é projetada para uso independente, sem garantias enterprise. A equipe de produto deve considerar isso no planejamento de redundância dos dispositivos IoT.
Disponibilidade sem SLA garantido
Não existe garantia formal de uptime. Qualquer interrupção, mesmo que breve, ocorre sem penalidades contratuais para o cliente.
Mudanças nos endpoints
Endereços como /v1/audio/speech podem sofrer ajustes internos. A estrutura do corpo JSON permanece estável, mas URLs podem mudar em atualizações menores.
Comunicação de alterações
Alterações significativas são comunicadas via email. Não há chat ao vivo ou telefone para tirar dúvidas urgentes sobre mudanças na API.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Implemente retries com backoff exponencial para respeitar os limites sem perder dados críticos.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
