Perguntas frequentes
Qual voz é melhor para assistentes de voz?
Para assistentes, as vozes nova (bright, upbeat) ou milo (friendly, conversational) são ideais. A escolha depende do tom da sua interface. Todas as 8 vozes suportam os 23 idiomas, incluindo português, garantindo consistência na experiência do usuário final.
MP3 ou WAV para dispositivos IoT?
Escolha MP3 para economizar largura de banda e armazenamento, ideal para dispositivos com recursos limitados. Use WAV se precisar de qualidade lossless ou latência mínima de decodificação. O formato PCM também está disponível para processamento de áudio bruto.
Como reduzir custos com TTS em massa?
O custo é fixo: $10 por 1 milhão de caracteres. Para otimizar, divida textos longos em partes de até 4096 caracteres e junte os arquivos. Use velocidades mais altas (até 4.0) para reduzir tempo de geração, mas mantenha a clareza.
A API suporta português do Brasil?
Sim, o português está na lista de 23 idiomas suportados. Você deve definir o campo language para pt-BR ou pt na requisição para garantir a pronúncia correta, pois o padrão para texto latino é inglês.
Qual o limite de caracteres por pedido?
O limite é de 4096 caracteres por requisição. Para textos maiores, divida o input em chunks menores, gere o áudio para cada parte e junte os arquivos resultantes. Isso garante que a síntese seja processada corretamente sem erros.
Posso usar a API para alertas de emergência?
Sim, a API é confiável para alertas. Voizes como atlas (neutral, news) ou sage (calm, instructional) transmitem clareza. Como não há SLA garantido, para criticidade extrema, considere redundância. A latência é previsível, mas pode haver filas sob carga.
Como gerenciar filas de áudio?
As requisições são processadas sequencialmente. Se houver alta demanda, sua solicitação pode aguardar na fila. Para IoT, implemente lógica de retry ou pré-gere áudios comuns. O tempo de geração é aproximadamente real-time para textos longos.
A API funciona sem internet?
Não. A síntese ocorre na nuvem via endpoint POST /v1/audio/speech. Você precisa de conexão para enviar o texto e receber o arquivo de áudio. Não há SDK offline ou instalação local de motor de TTS.
O que é watermark em áudio sintético?
Cada arquivo gerado contém uma marca d'água inaudível que identifica o áudio como síntese artificial. Isso é automático e não afeta a qualidade perceptível. É útil para rastreamento de origem e verificação de conteúdo gerado pela API.
Posso usar a API em apps móveis?
Sim, você pode usar a API diretamente de apps móveis via HTTP, alterando o base_url para https://api.spinlygame.com/v1. Não há SDK nativo específico para mobile, mas as bibliotecas padrão funcionam perfeitamente para integrar o áudio ao app.
Qual a diferença entre tts-1 e tts-1-hd?
Ambos usam o mesmo motor de síntese e têm o mesmo preço. A diferença é apenas a qualidade de áudio percebida. Para IoT, onde a clareza é crucial, teste ambas as opções para ver se a diferença justifica o uso.
Como fazer cache de áudio na IoT?
O limite de 4096 caracteres aplica-se ao texto da requisição, não ao arquivo gerado. O tamanho final do áudio varia conforme o formato selecionado (mp3, wav, opus, flac) e a duração da fala. Formatos sem perda, como FLAC, resultam em arquivos maiores, enquanto o MP3 oferece compressão mais eficiente para a mesma duração, sendo uma escolha comum para dispositivos IoT com restrições de armazenamento.
A API tem limite de tamanho de arquivo?
A API não impõe limite de arquivo, mas cada requisição aceita no máximo 4096 caracteres. Para textos longos, divida o conteúdo, gere o áudio para cada parte e junte os arquivos. O custo é baseado em caracteres, então textos extensos terão custos proporcionais.
Posso usar a API para leitura de livros?
Sim. O limite é de 4.096 caracteres por solicitação. Para textos longos, divida o conteúdo em partes e junte os arquivos de áudio gerados. A velocidade de geração é próxima do tempo real, aproximadamente 25 caracteres por segundo. O custo é de US$ 0,01 por mil caracteres, com cobranças apenas por solicitações bem-sucedidas.
Como funciona o top-up via TRON?
O top-up é feito exclusivamente com USDT na rede TRON (TRC-20), com mínimo de US$ 5. O crédito é creditado automaticamente em minutos após a transferência. Não aceitamos cartões, PayPal ou assinaturas. O saldo não expira e não há faturas com VAT. Para mais detalhes, consulte a seção de preços.
A API suporta acentos corretamente?
Sim. O motor suporta 23 idiomas, incluindo português, e detecta automaticamente o idioma pelo script. Se o texto estiver em latim mas não for inglês, defina o campo language explicitamente para garantir a pronúncia correta dos acentos e caracteres especiais.
Existe limite de uso por dispositivo?
O painel em /get-api-key/ exibe saldo, crédito e uso. Cada caractere conta. O custo é $0,01 por 1.000 caracteres. Pedidos falhos são gratuitos, sem cobrança. Para dispositivos IoT, o limite é de 60 requisições por minuto por chave. Textos longos devem ser divididos em partes de até 4.096 caracteres para garantir a síntese correta do áudio.
Seleção de Vozes para Ambientes Domésticos
Escolher a voz certa é crucial para a experiência do usuário em dispositivos IoT domésticos. A clareza e o tom devem corresponder ao contexto de uso, garantindo que as notificações sejam compreendidas imediatamente, seja em uma cozinha movimentada ou durante uma conversa familiar.
Aria para instruções claras
Com sua voz feminina, quente e clara, Aria é ideal para instruções técnicas ou narrativas. Sua articulação precisa ajuda dispositivos a entregarem comandos de configuração ou status de forma compreensível, mesmo em ambientes com ruído de fundo.
Milo para interações conversacionais
Milo oferece um tom masculino amigável e conversacional, perfeito para assistentes de voz ou feedback de interação natural. Sua abordagem direta torna as respostas do dispositivo mais naturais, aproximando a experiência do usuário de uma conversa humana.
Atlas para notícias e alertas
Atlas possui uma voz neutra e profissional, ideal para notícias, alertas de segurança ou notificações do sistema. Sua neutralidade garante que a informação seja transmitida sem distrações emocionais, mantendo o foco na clareza da mensagem crítica.
Escolha de Formato de Áudio
A escolha do formato de áudio impacta diretamente a latência e o consumo de dados em dispositivos IoT. O formato selecionado deve equilibrar a fidelidade do áudio sintetizado com a capacidade de decodificação do hardware embarcado e a largura de banda disponível na rede do ambiente doméstico.
MP3: equilíbrio entre tamanho e qualidade
O MP3 oferece uma compressão eficiente, mantendo a clareza necessária para instruções e notificações. É ideal para a maioria dos dispositivos smart home, onde o armazenamento e a largura de banda são limitados, mas a qualidade de voz precisa ser compreensível sem consumo excessivo de dados.
- Ampla compatibilidade com codecs de hardware existentes
- Tamanho de arquivo reduzido para economizar armazenamento
- Qualidade de voz suficiente para comandos e alertas
WAV: para dispositivos com alto processamento
O formato WAV fornece áudio não comprimido, eliminando a necessidade de decodificação complexa pelo dispositivo. Para hardware com recursos de processamento robustos, isso reduz a latência de reprodução, garantindo feedback auditivo imediato e previsível, crucial para interações em tempo real.
- Zero latência de decodificação de software
- Qualidade de áudio original sem perdas
- Ideal para dispositivos com CPU e memória abundantes
OPUS: eficiência para redes móveis
O OPUS oferece alta eficiência de compressão, sendo excelente para dispositivos que operam em redes móveis ou com largura de banda variável. Permite a transmissão de áudio de alta qualidade com menor consumo de dados, mantendo a clareza da voz mesmo em condições de rede menos ideais.
- Alta taxa de compressão para economizar dados
- Boa performance em redes com latência variável
- Suporte nativo em muitos dispositivos móveis e IoT
Otimização de Latência em Tempo Real
A latência de geração é previsível: textos longos geram áudio em tempo real (~25 caracteres/segundo), enquanto frases curtas levam alguns segundos. Como as requisições são processadas sequencialmente, sob carga, uma solicitação pode aguardar na fila, afetando a resposta imediata.
Para mitigar isso, antecipe a geração de áudio para interações comuns ou utilize buffering no dispositivo. Isso garante que o som seja reproduzido assim que o arquivo estiver disponível, minimizando a percepção de atraso pelo usuário final.
Previsibilidade de geração
A velocidade de processamento segue uma lógica linear: cerca de 25 caracteres de texto por segundo de áudio gerado. Isso permite estimar o tempo de espera para textos longos, mas frases curtas podem levar alguns segundos fixos.
Gestão de filas de processamento
As requisições são processadas uma após a outra. Sob alta carga, novas solicitações entram em fila, aumentando a latência percebida. Monitorar o status da fila ajuda a ajustar a frequência de chamadas ou agrupar textos menores.
Buffering de áudio em dispositivos
Implemente buffering no hardware embarcado para reproduzir o áudio imediatamente após o download parcial. Isso oculta a latência de rede e de geração, criando uma experiência de feedback auditivo mais fluida e responsiva.
Estratégias de Redução de Custos
Reduzir caracteres por requisição corta custos diretamente, já que o preço é de $0,01 por mil caracteres. Textos concisos evitam desperdício de créditos em notificações curtas. Para alertas repetitivos, como 'porta aberta', o cache de áudio local elimina requisições desnecessárias. Gere uma vez e reproduza localmente no dispositivo IoT.
Agrupe textos curtos em uma única chamada API, respeitando o limite de 4096 caracteres, para consolidar cobranças. Isso otimiza o custo por instrução e reduz a sobrecarga de conexão. Combine informações contextualmente para que uma única síntese entregue toda a mensagem necessária ao usuário.
Uso de frases curtas e diretas
O custo é linear: $0,01 por mil caracteres. Cada palavra extra conta. Prefira 'Sala aquecida' a 'A sala está agora aquecida a uma temperatura agradável.'
Textos diretos reduzem o tempo de geração e o volume de dados transmitidos, mantendo a clareza para o usuário final.
- Elimine artigos desnecessários.
- Use comandos imperativos.
- Remova redundâncias
Cache de áudio para alertas comuns
Alertas frequentes (ex: 'Ligada', 'Desligada') não precisam ser sintetizados a cada evento. Armazene o arquivo MP3 ou WAV no dispositivo.
Isso economiza créditos e reduz a latência, pois não há espera pela API para sons pré-gerados.
Use hashes do texto como chave de cache para garantir que a versão correta seja reproduzida.
- Armazene arquivos locais.
- Use chaves de hash.
- Atualize cache apenas se a voz mudar.
Agrupamento de requisições
Combine frases curtas em um único payload JSON, desde que o total não exceda 4096 caracteres.
Isso permite uma única cobrança por múltiplas instruções, otimizando o uso da cota de 60 requisições por minuto.
Ideal para sequências de feedback onde o usuário espera uma resposta contínua.
Integração Técnica com SDKs
A integração com o SDK da OpenAI é direta, exigindo apenas a reconfiguração da URL base. Isso permite reutilizar bibliotecas já consolidadas no ecossistema IoT sem a necessidade de aprender uma nova sintaxe de chamada.
O endpoint POST /v1/audio/speech aceita o mesmo formato JSON, mantendo a familiaridade para equipes que já utilizam APIs de geração de áudio.
Essa abordagem simplifica o desenvolvimento inicial, focando na adaptação da infraestrutura de rede ao invés da lógica de requisição.
Adaptação do OpenAI SDK
Utilize a biblioteca padrão da OpenAI, ajustando apenas o parâmetro de conexão.
O corpo da requisição permanece idêntico ao padrão TTS-1, facilitando a migração de protótipos.
Não há SDK proprietário, reduzindo dependências externas desnecessárias no dispositivo embarcado.
- Reutilize código existente de clientes OpenAI.
- Mantenha a estrutura de objetos JSON consistente.
- Evite dependências duplicadas no build do firmware.
Configuração de base_url
Aponte a URL base para https://api.spinlygame.com/v1.
Certifique-se de que o dispositivo tenha acesso estável a este endpoint.
A autenticação via header Bearer deve ser gerenciada com segurança, armazenando a chave de forma segura no dispositivo ou servidor proxy.
- Base URL: https://api.spinlygame.com/v1
- Endpoint: /v1/audio/speech
- Auth: Authorization: Bearer <sua-chave>
Tratamento de erros e retries
Implemente lógica de retry exponencial para falhas temporárias de rede.
Verifique o status da resposta para distinguir entre erros de sintaxe e limites de taxa.
Lembre-se que pedidos falhos são gratuitos, mas contagem de rate limit pode ocorrer.
- Retry em caso de timeout ou 5xx.
- Respeite o limite de 60 req/min.
- Retorne erro claro ao usuário final.
Design de UX para Áudio em IoT
O design de UX para áudio em IoT exige que o feedback sonoro seja imediato e contextual. Como o tempo de geração é aproximadamente real (25 caracteres por segundo), a experiência do usuário depende da previsibilidade da latência e da clareza da mensagem em ambientes domésticos variados.
Feedback sonoro imediato
Para notificações de dispositivos, utilize vozes curtas como 'Felix' ou 'Milo'. A geração de frases breves garante que o áudio seja entregue rapidamente, mantendo a interação fluida sem atrasos perceptíveis pelo usuário final.
- Prefira frases abaixo de 100 caracteres para respostas instantâneas
- Use vozes 'energetic' ou 'friendly' para alertas de status
Clareza em ambientes ruidosos
A voz 'Aria' oferece clareza narrativa ideal para instruções, enquanto 'Atlas' é neutra para notícias. Em ambientes com ruído de fundo, como cozinhas ou salas de estar, a escolha da voz correta e a formatação correta do texto são essenciais para a compreensão.
- Use 'Aria' para instruções passo a passo
- Evite velocidades superiores a 1.0x para maior clareza
Interrupção de áudio em progresso
Embora a API não suporte streaming em tempo real, o cliente pode interromper a reprodução do arquivo recebido. Gerencie a pausa no player do dispositivo IoT para evitar sobreposição de áudio quando um novo alerta é acionado imediatamente após o anterior.
- Implemente controle de playback no dispositivo cliente
- Encerre arquivos anteriores antes de iniciar novos
Gestão de Idiomas e Sotaques
O suporte multilíngue é fundamental para dispositivos IoT em mercados globais. Nossa API processa 23 idiomas, incluindo inglês, português, espanhol, japonês e árabe. Cada voz pode falar qualquer um desses idiomas nativamente, garantindo consistência acústica independente do idioma alvo.
A precisão na seleção de idioma evita sotaques indesejados. Para textos em português ou espanhol usando o alfabeto latino, o idioma é inferido por padrão como inglês. Definir explicitamente o parâmetro language garante a pronúncia correta.
Suporte a 23 idiomas disponíveis
Listamos 23 idiomas suportados, como chinês, russo, sueco e turco. Voces como Aria e Nova adaptam a prosódia automaticamente. Idiomas não listados, como vietnamita ou tailandês, não possuem suporte dedicado.
A consistência entre vozes mantém a experiência do usuário uniforme, seja o dispositivo falando em holandês ou malaio.
- Arabic, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Italian, Japanese, Korean, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Turkish
Forçamento de idioma via API
Use o campo language na requisição POST para forçar a síntese. Isso é crítico quando o script latino pode ser ambíguo, como textos em português ou espanhol.
Exemplo: POST /v1/audio/speech com language: 'pt-BR' garante que a voz Nova pronuncie corretamente os acentos, ignorando a inferência padrão para inglês.
Tratamento de textos multilíngues
Para textos que misturam idiomas, a API tenta inferir com base no script. Para maior controle, divida o texto em partes monolíngues ou defina o idioma dominante.
Lembre-se: cada requisição tem limite de 4096 caracteres. Para frases longas multilíngues, considere dividir e concatenar os arquivos de áudio resultantes.

Monitoramento de Uso e Limites
O controle preciso dos recursos é essencial para dispositivos IoT que operam com restrições de banda e processamento. A API fornece métricas claras sobre o consumo de caracteres, permitindo que equipes de produto calculem custos exatos antes da implementação em larga escala.
Com limites de taxa bem definidos, é possível dimensionar a infraestrutura de backend para evitar interrupções durante picos de uso, garantindo consistência nas notificações auditivas dos dispositivos conectados.
Rastreamento de caracteres gastos
Cada solicitação consome caracteres conforme o texto enviado, incluindo espaços e pontuação. O painel da conta exibe o saldo restante e o valor gasto em tempo real, facilitando o controle orçamentário para milhares de dispositivos.
Com o custo de $0,01 por mil caracteres, é possível prever gastos exatos para alertas frequentes ou feedbacks de voz curtos, evitando surpresas na fatura.
- Saldo em tempo real no painel
- Contagem exata de caracteres incl. espaços
- Custo fixo por 1.000 caracteres
Alerta de limite de requests
O limite de 60 requisições por minuto por chave API deve ser monitorado para evitar throttling. Em cenários de múltiplos dispositivos, distribua o tráfego entre chaves ou implemente filas locais no gateway.
Requisições falhas são gratuitas, mas contam para o limite de taxa. Implemente retries com backoff exponencial para respeitar os limites sem perder dados críticos.
- Limite: 60 req/min por chave
- Reinício do contador em 1 min
- Retries com backoff recomendado
Histórico de geração
Metadados de uso (tempo, status, caracteres) são mantidos para fins de cobrança e auditoria. Utilize esses dados para otimizar a frequência de notificações e ajustar a complexidade dos textos gerados.
O histórico permite identificar padrões de uso, como horários de pico ou dispositivos com maior consumo, facilitando o dimensionamento da infraestrutura IoT.
- Metadados retidos para billing
- Status de cada requisição
- Timestamp de geração
Privacidade e Conformidade de Dados
A API de síntese de voz do Spinly IoT Voice foi projetada para minimizar a retenção de dados sensíveis em dispositivos IoT e smart home. A arquitetura garante que o texto enviado para geração de áudio seja processado e entregue sem persistência de longo prazo, reduzindo riscos de exposição de comandos vocais ou instruções de controle.
Para fins de auditoria e faturamento preciso, apenas metadados essenciais da requisição são conservados. Isso inclui o timestamp exato, o volume de caracteres processados e o status da síntese (sucesso ou falha). Esses dados são estritamente necessários para calcular o custo por milhão de caracteres e garantir a transparência na cobrança.
Texto não armazenado
O conteúdo do campo input utilizado para gerar o áudio não é armazenado após a entrega do arquivo de som na resposta. Isso significa que o texto bruto enviado pelo seu dispositivo não permanece em nossos servidores de aplicação, oferecendo um nível elevado de privacidade para comandos específicos de usuários finais.
Metadados de uso retidos
Retemos apenas os metadados necessários para a operação e faturamento: data/hora da solicitação, número de caracteres processados e código de status HTTP. Esses registros permitem que você acompanhe o consumo exato de caracteres e valide a integridade das transações, sem reter o conteúdo semântico das mensagens enviadas.
Política de dados clara
Nossos dados de uso são mantidos exclusivamente para fins de controle de conta e histórico de geração. Não realizamos a venda de dados para terceiros nem utilizamos o texto dos usuários para treinar modelos de IA. A transparência é mantida através do painel de controle, onde você pode visualizar todo o histórico de requests e caracteres consumidos.
- Não usamos seu texto para treinar modelos de IA
- Metadados retidos apenas para faturamento e auditoria
- Sem venda de dados para terceiros
Testes e Validação em Dispositivos
Validar a experiência de voz em hardware embarcado exige testes práticos de latência e qualidade. Como a geração segue uma fila única, o tempo varia conforme a carga, sendo crucial medir o atraso real em condições de uso típico.
Os testes devem incluir simulação de falhas para garantir que o dispositivo mantenha a estabilidade mesmo quando a API retorna erros, evitando bugs silenciosos no hardware.
Teste de qualidade de áudio
Verifique se a voz escolhida, como Aria ou Milo, mantém clareza em ambientes ruidosos. O áudio gerado contém uma marca d'água inaudível que identifica o conteúdo como sintetizado, o que pode ser verificado por ferramentas específicas se necessário.
- Testar diferentes velocidades (0.25–4.0) para adequação ao contexto.
- Verificar formatos WAV vs MP3 em hardware específico.
Validação de latência
Meça o tempo desde o envio do POST até a recepção do arquivo. Textos longos geram áudio em tempo real, mas frases curtas podem levar alguns segundos devido ao processamento sequencial.
Considere o buffering no dispositivo para suavizar variações de rede e garantir uma reprodução fluida sem interrupções perceptíveis.
Simulação de falhas
Simule erros de rede e limites de taxa para validar o comportamento do firmware. Como não há garantia de SLA, o sistema deve lidar gracefulmente com timeouts.
Teste a recuperação após falhas, garantindo que o dispositivo não trave nem perca o estado da interação durante a síntese.
- Simular 429 (Rate Limit) e 500 (Server Error).
- Testar timeout de rede em conexões instáveis.
Escalabilidade para Milhares de Dispositivos
Para escalar a produção de áudio em milhares de dispositivos IoT, o limite de 60 requisições por minuto por chave torna a gestão de múltiplos tokens essencial. Como cada conta possui apenas uma chave ativa, distribuir o tráfego entre várias contas evita gargalos de processamento em picos de notificações simultâneas.
A arquitetura deve considerar que as requisições são processadas em fila, uma após a outra. Utilizar múltiplas chaves permite paralelizar o trabalho, mantendo a latência previsível mesmo sob carga elevada, sem depender de um único ponto de falha na geração de áudio.
Gestão de múltiplas chaves API
Crie contas adicionais e emita novas chaves para isolar cargas de trabalho específicas. Como a chave antiga é invalidada imediatamente ao emitir uma nova, planeje a transição para evitar interrupções nos dispositivos já em campo.
- Crie contas separadas para diferentes regiões ou linhas de produtos.
- Utilize o endpoint /v1/voices para verificar limites e disponibilidade antes de escalar.
- Monitore o saldo para garantir que o custo escalonável permaneça previsível.
Distribuição de carga
Distribua as requisições entre as chaves disponíveis para evitar o limite de 60 requests/min. Para textos longos, divida em partes de 4096 caracteres e processe-as sequencialmente ou em paralelo, conforme a necessidade de sincronia.
- Implemente um balanceador simples que roteie requisições para diferentes chaves.
- Agregue respostas de áudio curto para reduzir o número de chamadas individuais.
- Considere a latência de fila ao projetar o tempo de resposta do dispositivo.
Monitoramento de saúde da API
Rastreie o status das requisições e o tempo de geração. Como não há SLA oficial, monitore manualmente os tempos de resposta para ajustar a estratégia de distribuição de carga e garantir a experiência do usuário final.
- Verifique o endpoint /v1/models para confirmar a disponibilidade do serviço.
- Registre o tempo de resposta médio por chave API.
- Alerte sobre falhas para reprocessamento imediato sem custo adicional.
Próximos Passos e Recursos
A documentação completa está disponível na seção /docs/, detalhando todos os parâmetros de requisição, formatos de áudio e exemplos de código para integração rápida com o SDK do OpenAI.
Crie sua conta em /get-api-key/ para obter sua chave API imediatamente. Novos usuários recebem um crédito gratuito de $0,50 para testar a geração de áudio sem compromisso.
Acesso à documentação completa
Explore os endpoints /v1/audio/speech e /v1/voices para entender as capacidades do motor de síntese. A documentação inclui exemplos práticos de curl e configurações de velocidade e formato.
- Referência completa de parâmetros
- Exemplos de integração SDK
- Guia de formatos de áudio
Criação de conta e crédito grátis
Registre-se usando Google ou e-mail para acessar seu painel. O crédito inicial de 7 dias permite validar a qualidade do áudio em seus dispositivos IoT antes de qualquer investimento.
- Crédito de $0,50
- Validação de 50.000 caracteres
- Sem cartão de crédito
Sua API pronta para uso
Comece a gerar áudio agora mesmo. Utilize sua chave Bearer para enviar textos e receber arquivos de áudio em segundos, integrando diretamente ao seu hardware embarcado.
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.
