Documentação da API de Texto para Voz para Desenvolvedores IoT

Por Equipe editorial Spinly IoT Voice · Atualizado 2026-11-18

Esta documentação detalha a integração da API de síntese de voz Spinly IoT em dispositivos embarcados e ecossistemas de smart home. Você aprenderá a enviar texto via JSON e receber áudio com latência previsível, ideal para notificações de sensores e assistentes de voz que exigem custos escaláveis e formatos leves.

Destinada a equipes de produto e desenvolvedores, a página cobre autenticação, parâmetros de voz, limites de taxa e exemplos práticos em cURL e OpenAI SDK. Utilize estas especificações para implementar feedback auditivo em hardware, garantindo conformidade técnica sem funcionalidades inventadas ou suposições sobre suporte.

Documentação da API de Texto para Voz para Desenvolvedores IoT

Perguntas frequentes

Qual é o endpoint principal da API?

O endpoint principal é POST https://api.spinlygame.com/v1/audio/speech. Você envia texto e recebe um arquivo de áudio. A estrutura da requisição é idêntica à da OpenAI, facilitando a integração em dispositivos IoT e sistemas de smart home existentes.

Preciso de um SDK específico?

Não. A API utiliza o mesmo formato de requisição da OpenAI. Você pode usar os SDKs oficiais da OpenAI alterando o base_url para https://api.spinlygame.com/v1. Não existe SDK proprietário da Spinly IoT Voice, garantindo flexibilidade técnica.

Como autentico as requisições?

Utilize o cabeçalho Authorization: Bearer tts-... com sua chave única. Cada conta possui apenas uma chave ativa por vez. Você pode emitir uma nova chave a qualquer momento, invalidando imediatamente a anterior para segurança.

Qual a diferença entre tts-1 e tts-1-hd?

Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço. A escolha entre 'tts-1' e 'tts-1-hd' não impacta o custo nem a qualidade percebida do áudio gerado para notificações ou assistentes de voz em IoT.

Posso definir a velocidade da voz?

Sim. O campo 'speed' aceita valores entre 0.25 e 4.0. Isso permite ajustar a velocidade da fala para notificações urgentes ou instruções detalhadas, adaptando o feedback auditivo aos diferentes contextos de uso dos dispositivos embarcados.

O que acontece se exceder 60 requests/min?

As requisições são processadas sequencialmente. Se o limite de 60 requests por minuto for excedido, as solicitações aguardam na fila. Isso garante a integridade da geração de áudio, embora possa aumentar a latência em picos de uso.

Quais formatos de áudio posso receber?

Você pode solicitar os formatos mp3, wav, opus, flac ou pcm. A escolha depende da compatibilidade do hardware IoT e dos requisitos de largura de banda. Todos os formatos são gerados diretamente pela API via JSON.

A API retorna erro se o texto for grande?

Não. O limite é de 4096 caracteres por requisição. Para textos maiores, você deve dividir o conteúdo em partes de até 4096 caracteres e juntar os arquivos de áudio resultantes.

Como funcionam os 10 requests iniciais?

Após a criação da conta, você tem limite de 10 requests por minuto. Após o primeiro top-up, o limite aumenta para 60 requests por minuto. Isso permite testar a integração antes de escalar o volume de dispositivos.

Posso usar a API com Node.js?

Sim. Como a interface é compatível com a OpenAI, você pode utilizar o SDK da OpenAI para Node.js. Basta configurar o base_url para https://api.spinlygame.com/v1 e usar sua chave API para realizar as chamadas de síntese.

Onde encontro a lista de vozes?

Acesse o endpoint GET /v1/voices. Ele retorna a lista completa das 8 vozes disponíveis, os idiomas suportados, os formatos de áudio e as informações de preço, facilitando a configuração dinâmica nos aplicativos de controle de smart home.

A API suporta SSML para IoT?

Não. A API não oferece suporte a SSML, nem a dicionários de fonemas ou lexicons personalizados de pronúncia. A síntese é baseada estritamente no texto enviado e nas configurações básicas de voz e velocidade disponíveis no endpoint.

Existe limite de tamanho de texto?

Sim, o limite é de 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos longos, é necessário implementar a lógica de divisão em partes no lado do cliente ou servidor e concatenar os arquivos de áudio gerados.

Como faço rollback da chave API?

Basta emitir uma nova chave na página da conta. A chave antiga é invalidada imediatamente assim que a nova é gerada. Não há período de transição; o uso da chave antiga cessa instantaneamente após a rotação.

Primeira solicitação

curl

curl https://api.spinlygame.com/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.spinlygame.com/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.spinlygame.com/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 e Chave API

Ilustração de onda sonora para: Autenticação e Chave API

Para utilizar a API de síntese de voz na Spinly IoT, é necessário primeiro obter uma chave de API válida. O acesso é feito através do painel de controle em /get-api-key/, onde é possível criar uma conta via Google ou e-mail.

Essa chave será usada para autenticação em todas as requisições, garantindo que o uso dos recursos de TTS seja rastreado e cobrado corretamente conforme o volume de caracteres processados.

Obtenção de chave no painel

Obtenção de chave no painel

Acesse /get-api-key/ para registrar sua conta. Se usar Google, recebe $0,50 de crédito gratuito por 7 dias; contas criadas com e-mail não possuem esse bônus inicial.

O painel exibe a chave ativa, saldo atual e histórico de uso, permitindo o acompanhamento preciso dos custos para seus dispositivos IoT.

Header Authorization Bearer

Header Authorization Bearer

Inclua o cabeçalho Authorization: Bearer tts-... em todas as requisições HTTP. Use o prefixo tts- seguido da string gerada no painel.

Essa autenticação é necessária para identificar sua conta e validar o saldo disponível antes do processamento da síntese.

Revoque e emissão de nova chave

Caso haja suspeita de vazamento ou necessidade de rotação, emita uma nova chave no painel. A chave anterior deixa de funcionar imediatamente.

Essa funcionalidade é essencial para segurança em ambientes de desenvolvimento e produção de hardwares embarcados com múltiplas instâncias.

Endpoint principal de síntese

Ilustração de onda sonora para: Endpoint principal de síntese

O endpoint principal /v1/audio/speech é o núcleo da API, onde textos são convertidos em arquivos de áudio. As requisições são processadas sequencialmente; para notificações em tempo real, considere a latência de processamento.

Método POST para /v1/audio/speech

Envie uma requisição POST para https://api.spinlygame.com/v1/audio/speech. O corpo da mensagem deve ser do tipo JSON contendo os parâmetros de síntese.

Corpo JSON com parâmetros

Inclua model ("tts-1" ou "tts-1-hd"), input (texto até 4096 caracteres), voice (um dos 8 presets), response_format e speed (0.25–4.0). O campo language é opcional.

Retorno do arquivo de áudio

A resposta contém o arquivo de áudio gerado. Se a síntese falhar, não há cobrança. Para textos longos, divida em partes e junte os arquivos.

Exemplo de requisição cURL

Ilustração de onda sonora para: Exemplo de requisição cURL

Para integrar a síntese de voz ao seu dispositivo IoT, utilize o endpoint principal enviando o texto bruto. O comando abaixo demonstra uma requisição válida para geração de áudio imediato.

Este exemplo configura o modelo padrão, seleciona uma voz específica e define o formato de saída. Ajuste os parâmetros conforme a necessidade de latência e qualidade do seu hardware embarcado.

Comando pronto para copiar

Utilize este comando cURL para testar a integração diretamente no terminal. Substitua SEU_TOKEN pela chave obtida no painel e ajuste o texto de entrada.

O comando envia uma solicitação POST para o endpoint de síntese, retornando o arquivo de áudio binário para o arquivo output.mp3.

  • Substitua SEU_TOKEN pela sua chave API ativa.
  • Ajuste o valor de input para o texto desejado.

Configuração de modelo e voz

Defina o modelo tts-1 para processamento padrão ou tts-1-hd para maior qualidade. Selecione uma das oito vozes disponíveis, como nova para notificações ou atlas para leitura de dados.

A escolha da voz impacta a percepção do usuário final. Todas as vozes suportam os idiomas listados na documentação, com detecção automática ou especificação explícita.

Definição de formato de saída

Especifique o formato de saída via parâmetro response_format. MP3 é recomendado para compatibilidade geral em dispositivos com recursos limitados.

Opções como WAV, OPUS, FLAC e PCM permitem otimizar o tamanho do arquivo e a fidelidade conforme a largura de banda disponível no dispositivo IoT.

  • MP3: compatibilidade universal.
  • WAV: alta fidelidade sem compressão.

Integração com OpenAI SDK

Ilustração de onda sonora para: Integração com OpenAI SDK

Alteração do base_url

Os SDKs oficiais da OpenAI funcionam com nossa API alterando o base_url para https://api.spinlygame.com/v1. Esta configuração permite que o cliente HTTP padrão roteie as requisições diretamente para o endpoint de síntese, mantendo a estrutura de payload idêntica ao padrão do OpenAI.

Uso do mesmo cliente de código

Com o base_url ajustado, o mesmo objeto de cliente de código permanece válido para chamadas POST em /v1/audio/speech. Não é necessário escrever parsers personalizados ou lidar com autenticação adicional, pois o cabeçalho Bearer tratado pelo SDK é suficiente para autorizar a geração de áudio.

Vantagens para desenvolvedores existentes

Equipes de IoT já familiarizadas com a sintaxe Python ou Node.js da OpenAI podem integrar a Spinly IoT Voice sem reescrever a camada de chamadas HTTP. A consistência na forma das requisições reduz o tempo de integração e minimiza erros de implementação em dispositivos embarcados.

Parâmetros de entrada

Ilustração de onda sonora para: Parâmetros de entrada

O corpo da requisição POST para /v1/audio/speech define como o texto será convertido em áudio. Os campos obrigatórios incluem o modelo, o texto de entrada (input) e a voz selecionada, enquanto opções como velocidade e idioma permitem ajustes finos na geração.

O campo input aceita até 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos mais longos, é necessário dividir o conteúdo em partes e juntar os arquivos de áudio resultantes. A velocidade varia de 0.25 a 4.0, permitindo acelerar ou desacelerar a narração conforme a necessidade do dispositivo IoT.

Modelo tts-1 vs tts-1-hd

A API oferece dois identificadores de modelo: "tts-1" e "tts-1-hd". Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço de $0,01 por 1.000 caracteres. A escolha entre eles não altera o preço nem a latência, servindo principalmente para fins de compatibilidade com SDKs que esperam um identificador de modelo específico.

Ambos os modelos têm o mesmo motor e preço; a escolha depende apenas da compatibilidade com o SDK utilizado. Não há diferença técnica nos arquivos gerados entre os dois modelos.

Vozes disponíveis (8 presets)

O campo voice aceita um dos oito presets disponíveis, categorizados por gênero e tom. As vozes são baseadas em gravações licenciadas do LibriTTS-R (CC BY 4.0) e do LibriVox, garantindo uma qualidade auditiva consistente para notificações e assistentes de voz.

Cada arquivo gerado contém uma marca d'água inaudível que identifica o áudio como sintético. A escolha da voz deve considerar o contexto de uso: narrativas, alertas ou interações conversacionais.

  • Aria: feminina, narradora clara e quente
  • Nova: feminina, brilhante e animada
  • Luna: feminina, suave e ideal para histórias
  • Sage: feminina, calma e instrucional
  • Felix: masculino, energético e promocional
  • Milo: masculino, amigável e conversacional
  • Atlas: masculino, neutro e jornalístico
  • Orion: masculino, profundo e documental

Velocidade e idioma opcional

O parâmetro speed ajusta a velocidade da fala entre 0.25 e 4.0, permitindo adaptar o tempo de resposta do dispositivo para interfaces de usuário mais dinâmicas ou calmas. O idioma (language) é opcional; se não fornecido, o sistema tenta adivinhar o idioma com base no script (texto em latino assume inglês).

Para textos em línguas como francês, alemão ou espanhol escritos em latim, defina o idioma explicitamente para evitar interpretações incorretas. O sistema suporta 23 idiomas, mas não inclui vietnamita, indonésio, tailandês, ucraniano, romeno, tcheco, bengali ou outros não listados.

Parâmetros de entrada

Formatos de saída suportados

Ilustração de onda sonora para: Formatos de saída suportados

O formato de áudio retornado pela API é configurável via parâmetro response_format, permitindo ajustar o equilíbrio entre compatibilidade e eficiência de armazenamento. A escolha adequada depende da capacidade de processamento dos dispositivos IoT e dos requisitos de latência do ecossistema smart home.

Cada arquivo gerado pode conter uma marca d'água inaudível que identifica o áudio como sintetizado, garantindo a rastreabilidade da origem da voz em sistemas de feedback auditivo.

MP3 para compatibilidade geral

O MP3 é a opção padrão para a maioria dos dispositivos embarcados e aplicativos móveis devido à sua ampla aceitação em codecs nativos. O formato MP3 oferece compressão com tamanho de arquivo reduzido, adequado para dispositivos com recursos limitados.

  • Suporte nativo na maioria dos sistemas operacionais de IoT
  • Tamanho de arquivo compacto para redução de custos de armazenamento

WAV para alta fidelidade

O formato WAV fornece áudio PCM não compactado, preservando a fidelidade original da voz gerada. É ideal para dispositivos com capacidade de processamento suficiente para lidar com arquivos maiores ou quando a qualidade sonora é crítica para a experiência do usuário em assistentes de voz.

  • Áudio sem perda de compressão
  • Ideal para testes de qualidade e gravações locais de alta precisão

OPUS, FLAC e PCM para eficiência

OPUS oferece compressão eficiente com boa qualidade, sendo excelente para transmissão em redes com largura de banda limitada. FLAC proporciona compressão sem perda, ideal para arquivamento de dados de voz. PCM fornece dados brutos para processamento posterior em tempo real em hardware dedicado.

  • OPUS: alta eficiência para transmissão em redes restritas
  • FLAC: compressão sem perda para arquivamento
  • PCM: dados brutos para processamento imediato

Limites e Taxas (Rate Limits)

Ilustração de onda sonora para: Limites e Taxas (Rate Limits)

A API impõe um limite padrão de 60 requisições por minuto por chave de API. Esse controle garante estabilidade no serviço de síntese de voz para dispositivos IoT e sistemas de notificação em tempo real.

60 requisições por minuto

O limite padrão de 60 requisições por minuto aplica-se a cada chave ativa. Esse valor é suficiente para a maioria dos cenários de notificação e feedback auditivo em hardwares embarcados.

Limite de 10 rpm antes do top-up

Contas sem top-up ativo operam com um limite reduzido de 10 requisições por minuto. Após o primeiro top-up via USDT (TRC-20), o limite aumenta para 60 rpm.

  • Limite reduzido para contas sem crédito carregado
  • Restauração imediata após confirmação de pagamento

Gerenciamento de fila de processos

Tratamento de erros comuns

Ilustração de onda sonora para: Tratamento de erros comuns

O tratamento de erros na API de síntese de voz para IoT requer atenção aos limites de taxa e à validação de parâmetros. Erros 429 indicam que o limite de 60 requisições por minuto foi atingido, enquanto erros 400 sinalizam configurações inválidas no corpo da requisição JSON.

Erro 429 (limite excedido)

Quando o limite de 10 rpm (antes do top-up) ou 60 rpm é alcançado, a API retorna status 429. As requisições subsequentes são recusadas até que o tempo de renovação ocorra. É recomendado implementar lógica de retry com backoff exponencial nos dispositivos embarcados para evitar sobrecarga.

Erro 400 (parâmetros inválidos)

Este erro ocorre quando o corpo JSON contém campos ausentes, formatos incorretos ou valores fora do permitido, como voz inexistente ou texto acima de 4096 caracteres. Verifique a estrutura da requisição conforme a documentação para garantir que todos os campos obrigatórios estejam presentes e válidos.

Retorno de status de falha

Se a síntese falhar após o processamento, o crédito é devolvido integralmente. O status de falha indica que o áudio não foi gerado, mas o custo foi revertido. Isso garante que apenas requisições bem-sucedidas resultem em charges na conta do desenvolvedor IoT.

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.

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. curl documentation
  3. openai-node on GitHub
  4. Node.js documentation
  5. LibriTTS-R paper (arXiv 2305.18802)
  6. LibriVox public-domain audiobooks
  7. Creative Commons Attribution 4.0
  8. TRON developer hub: TRC-20
  9. FFmpeg documentation
  10. openai-python on GitHub
  11. Python documentation
  12. ISO 639 language codes

Mais neste site