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.mp3Python (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 | |
|---|---|
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 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
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
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
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
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_TOKENpela sua chave API ativa. - Ajuste o valor de
inputpara 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
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
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.

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)
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
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.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
