Documentação Técnica da API de Texto para Fala

Por Equ editorial Spinaudio · Atualizado 2026-11-19

Esta documentação explica como integrar nossa API de texto para fala em seu LMS ou plataforma de cursos. Você aprenderá a enviar requisições JSON simples e receber arquivos de áudio prontos para reprodução. O fluxo é direto: autenticar, definir modelo e voz, e obter o arquivo. Não há complexidade desnecessária para desenvolvedores que buscam acessibilidade rápida.

Utilizamos o formato de requisição compatível com o SDK oficial da OpenAI, facilitando a migração. Basta ajustar a base URL e usar sua chave API. Esta página cobre autenticação, parâmetros de entrada, formatos de saída e limites técnicos. Ideal para quem precisa transformar materiais didáticos em áudio com consistência e clareza.

Documentação Técnica da API de Texto para Fala

Perguntas frequentes

Qual é o endpoint para gerar áudio?

O endpoint é POST https://api.spinaud.info/v1/audio/speech. Envie o texto e as configurações em formato JSON no corpo da requisição para receber o arquivo de áudio sintetizado diretamente na resposta da API.

Como autenticar a requisição?

Autentique enviando o cabeçalho Authorization: Bearer tts-... no cabeçalho HTTP da solicitação. Utilize sua chave única de API, que pode ser renovada a qualquer momento na sua conta, substituindo a anterior imediatamente.

Qual o limite máximo de caracteres?

O campo input aceita até 4096 caracteres por requisição. Para textos mais longos, divida o conteúdo em partes dentro desse limite e junte os arquivos de áudio resultantes para criar o áudio completo.

Posso mudar a velocidade do áudio?

Sim, o parâmetro speed aceita valores entre 0.25 e 4.0. Isso permite acelerar ou desacelerar a fala sintetizada para se adequar melhor ao ritmo de aprendizado ou preferência do ouvinte.

Como especificar o idioma?

Use o parâmetro language com o código ISO opcional. Se não definido, o idioma é adivinhado pelo script; para textos em latim fora do inglês, defina explicitamente o idioma para evitar erros de pronúncia.

Quais formatos de áudio estão disponíveis?

Você pode solicitar os formatos mp3, wav, opus, flac ou pcm através do parâmetro response_format. Escolha o formato que melhor se integra ao seu player de áudio ou sistema de distribuição de conteúdo.

Funciona com a biblioteca oficial do OpenAI?

Sim, o formato da requisição é idêntico ao endpoint de fala do OpenAI. Basta alterar o base_url para https://api.spinaud.info/v1 e usar sua chave de API Spinaudio com as bibliotecas oficiais.

Qual a taxa limite de requisições?

O limite é de 60 requisições por minuto por chave (10/min antes do primeiro recarga). As solicitações são processadas em fila, podendo haver espera sob carga. Monitore seus limites na página de uso.

Primeira solicitação

curl

curl https://api.spinaud.info/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.spinaud.info/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.spinaud.info/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 consumir a API de texto para fala, inclua o cabeçalho de autenticação em todas as requisições. O formato exige o prefixo Bearer seguido pela sua chave única.

Sua chave é emitida ao criar a conta e pode ser visualizada na área do painel. Mantenha-a segura, pois ela é o único meio de identificar sua conta e debitar o uso.

Header Authorization

Header Authorization

Envie o header HTTP Authorization: Bearer tts-SEU_CHAVE em cada solicitação POST ou GET. Sem este token, a API retorna erro de autorização.

Geração de chave

Geração de chave

Acesse a página /get-api-key/ para se registrar com Google ou email. Sua chave única aparece imediatamente no painel, junto com seu saldo e histórico de uso.

Rotação de chave

Você pode gerar uma nova chave a qualquer momento pelo painel. A chave antiga é invalidada instantaneamente, garantindo que acessos não autorizados sejam bloqueados imediatamente.

Endpoint principal

Ilustração de onda sonora para: Endpoint principal

O endpoint principal processa sua solicitação de síntese de voz enviando texto para a API. Utilize o método POST no caminho /v1/audio/speech para receber o arquivo de áudio gerado.

O corpo da requisição deve ser JSON contendo o modelo, o texto e a voz desejada. A resposta retornará o arquivo de áudio diretamente no corpo da resposta HTTP.

Método POST

Envie requisições POST para https://api.spinaud.info/v1/audio/speech.

JSON body

Inclua o campo model ("tts-1" ou "tts-1-hd"), o texto em input (máximo 4096 caracteres) e o voice desejado. Opcionalmente, defina response_format, speed e language.

  • Modelo: tts-1 ou tts-1-hd
  • Input: texto até 4096 caracteres
  • Voice: uma das 8 vozes disponíveis
  • Response format: mp3, wav, opus, flac, pcm

Exemplo curl

Exemplo básico para testar a integração imediatamente após obter sua chave API.

```bash curl -X POST https://api.spinaud.info/v1/audio/speech \ -H "Authorization: Bearer SUA_CHAVE_AQUI" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Olá, este é um teste de API.", "voice": "nova"}' \ --output audio.mp3 ```

Parâmetros de requisição

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

Os parámetros de entrada definem como o texto será processado e qual voz será utilizada. Cada requisição aceita um único bloco de texto, com limite máximo de 4096 caracteres por chamada.

Para textos longos, é necessário dividir o conteúdo em partes menores e juntar os arquivos de áudio gerados. Espaços e pontuação contam como caracteres na contagem.

Modelo tts-1

O campo model aceita os valores "tts-1" ou "tts-1-hd". Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço de $0,01 por 1.000 caracteres.

Parâmetro input

O texto a ser convertido deve ser enviado no campo input. O limite é de 4096 caracteres por requisição.

Se o texto exceder esse limite, divida-o em partes e concatene os arquivos de áudio resultantes.

Parâmetro voice

Escolha entre 8 vozes predefinidas, classificadas por gênero e tom. Exemplos: "aria" (narração clara) ou "atlas" (neutro, estilo noticiário).

Cada voz pode falar qualquer um dos 23 idiomas suportados.

  • aria (feminino, narrador claro)
  • nova (feminino, animado)
  • luna (feminino, suave)
  • sage (feminino, instrucional)
  • felix (masculino, energético)
  • milo (masculino, conversacional)

Formatos de saída

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

Escolha o formato de áudio que melhor se adapta à sua infraestrutura de entrega e aos players dos seus alunos. Cada formato oferece um equilíbrio diferente entre compatibilidade, qualidade e tamanho de arquivo.

MP3

Formato universalmente suportado por navegadores e dispositivos móveis. Ideal para distribuição geral, garantindo que seus cursos sejam acessíveis sem necessidade de plugins extras.

  • Ampla compatibilidade
  • Tamanho de arquivo otimizado

WAV

Áudio sem perda de compressão, mantendo a fidelidade original da gravação. Recomendado para edições internas ou quando a qualidade de estúdio é prioritária.

  • Qualidade sem perda
  • Arquivos maiores

OPUS e FLAC

OPUS oferece compressão eficiente com boa qualidade. FLAC preserva a qualidade lossless. Ambos são opções técnicas para casos específicos.

  • OPUS: Alta eficiência
  • FLAC: Lossless compactado

Velocidade e idioma

Ilustração de onda sonora para: Velocidade e idioma

A API permite ajustar a velocidade de fala entre 0.25x e 4.0x, facilitando a adaptação do áudio ao ritmo de leitura dos alunos. Para textos longos, o processamento ocorre sequencialmente, com velocidade média de geração próxima ao tempo real.

Range de velocidade

Ajuste o parâmetro speed para controlar a velocidade da voz. Valores entre 0.25 e 4.0 são aceitos, permitindo desde narração lenta até leitura acelerada para revisões rápidas.

Código ISO opcional

Defina o idioma enviando o código ISO (ex: pt-BR, en-US). Isso garante a pronúncia correta, especialmente para textos em línguas não inglesas escritas com alfabeto latino.

  • Suporte para 23 idiomas específicos.
  • Recomendado para evitar ambiguidades na pronúncia.

Detecção automática

Se o campo language não for informado, o sistema tenta adivinhar o idioma com base no script. Textos em latinos sem código definido assumem inglês por padrão.

Velocidade e idioma

Integração com SDK

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

A API Spinaudio segue o formato JSON do endpoint de fala da OpenAI, permitindo o uso direto dos SDKs oficiais da biblioteca com apenas uma configuração mínima. Isso elimina a necessidade de escrever código HTTP personalizado para inicialização e serialização de payload.

SDK OpenAI

Utilize o pacote openai do Python ou JavaScript. A compatibilidade é garantida porque a estrutura do corpo da requisição é idêntica à da OpenAI.

Base URL customizada

A única alteração necessária é apontar o cliente para a base URL correta: https://api.spinaud.info/v1. Isso redireciona todas as chamadas para nossos servidores sem mudar a lógica do código.

Exemplo Python

Instale a biblioteca e configure o ambiente com sua chave. O código abaixo demonstra a configuração básica para gerar áudio instantaneamente.

  • Instale com: pip install openai
  • Configure OPENAI_API_KEY com sua chave Spinaudio
  • Defina base_url para https://api.spinaud.info/v1

Limites e erros

Ilustração de onda sonora para: Limites e erros

A API respeita limites claros para garantir estabilidade. Você tem direito a 60 requisições por minuto por chave ativa (ou 10/min até o primeiro depósito). O limite de entrada é de 4.096 caracteres por chamada.

60 requisições/minuto

O processamento é sequencial; em alta demanda, sua solicitação pode aguardar na fila. Isso garante que o serviço permaneça estável para todos os usuários simultaneamente.

Limite de caracteres

Cada requisição aceita no máximo 4.096 caracteres. Para textos longos, divida o conteúdo em partes menores e junte os arquivos de áudio gerados sequencialmente.

Códigos de erro

Se a síntese falhar, a cobrança é devolvida integralmente. Erros comuns incluem excesso de limite ou formato JSON inválido. Consulte a documentação completa para detalhes técnicos.

Voices endpoint

Ilustração de onda sonora para: Voices endpoint

Explore a lista completa de vozes disponíveis e seus formatos suportados diretamente via API.

A rota fornece metadados essenciais para planejar a integração técnica com sua plataforma LMS.

GET /v1/voices

Envie uma requisição GET para https://api.spinaud.info/v1/voices para recuperar o catálogo atual de vozes, idiomas e formatos de áudio suportados.

Listagem de vozes

A resposta retorna detalhes de todas as oito vozes disponíveis, permitindo filtrar por gênero ou idioma nativo para selecionar a melhor opção para seu conteúdo didático.

Metadados de preço

A rota retorna informações sobre os formatos de saída suportados e o preço padrão da API.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. A conversão de texto para fala elimina barreiras de leitura para alunos com baixa visão ou cegueira.

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. OpenAI API reference: create speech
  3. W3C WAI: making audio and video accessible
  4. openai-python on GitHub
  5. TRON developer hub: TRC-20
  6. LibriTTS-R corpus (OpenSLR 141)
  7. openai-node on GitHub
  8. Tether (USDT)
  9. LibriVox public-domain audiobooks
  10. ISO 639 language codes
  11. Node.js documentation
  12. FFmpeg documentation

Mais neste site