Perguntas frequentes
Como faço a autenticação na API?
Envie o cabeçalho Authorization: Bearer tts-... com sua chave única. Cada conta possui apenas uma chave ativa; ao emitir uma nova, a anterior é invalidada imediatamente. A chave é obtida na página /get-api-key/ após o cadastro via Google ou e-mail.
Qual é o endpoint para gerar áudio?
Use POST https://api.st650.info/v1/audio/speech com corpo JSON. Inclua model, input, voice, response_format e speed. O formato da requisição é idêntico ao da OpenAI, facilitando a integração para educadores e desenvolvedores que já utilizam APIs similares.
Posso usar o SDK da OpenAI?
Sim. Como a forma da requisição é a mesma, você pode usar os SDKs oficiais da OpenAI. Basta alterar o base_url para https://api.st650.info/v1 e utilizar a chave da Folha Narradora. Não oferecemos SDK proprietário próprio.
Quais formatos de áudio posso receber?
Você pode solicitar os formatos mp3, wav, opus, flac ou pcm. Escolha o formato mais adequado para sua plataforma educacional ou dispositivo de reprodução. A escolha do formato não altera o preço ou a qualidade da síntese de voz.
Qual o limite de caracteres por texto?
Cada requisição suporta até 4096 caracteres, incluindo espaços e pontuação. Para textos longos, você deve dividir o conteúdo em partes menores e juntar os arquivos de áudio resultantes. Isso garante que cada lote de texto seja processado corretamente.
Posso controlar a velocidade da fala?
Sim, o parâmetro speed aceita valores entre 0.25 e 4.0. Isso permite ajustar a velocidade da narração para histórias infantis, tornando-a mais lenta para crianças menores ou mais rápida para revisões. O padrão é 1.0.
Como especificar o idioma da narração?
Use o campo language com o código ISO. Se não for definido, o sistema tenta adivinhar pelo script (texto latino assume inglês). Para textos em português ou outros idiomas latinos, defina explicitamente o idioma para evitar erros de pronúncia.
A API retorna o áudio em streaming?
Não. A API retorna o arquivo de áudio completo na resposta. Não há suporte para streaming, WebSockets ou áudio parcial em tempo real. O arquivo é gerado e entregue após o processamento da requisição, o que pode levar alguns segundos.
O que acontece se exceder o limite de requisições?
O limite é de 60 requisições por minuto por chave (10 antes do primeiro depósito). Se exceder, as requisições podem ser rejeitadas ou processadas fora de ordem. As requisições falhas não são cobradas, mas o áudio não será gerado.
Como lidar com textos muito longos?
Divida o texto em partes de até 4096 caracteres. Envie cada parte via API e, em seguida, junte os arquivos de áudio resultantes. A velocidade média é de cerca de 25 caracteres por segundo, então textos longos levam tempo real.
Existe suporte para SSML?
Não. A API não suporta marcação SSML, nem dicionários de fonemas ou lexicons personalizados para pronúncia. A narração é baseada estritamente no texto fornecido e nos parâmetros de voz e velocidade disponíveis. Não há tags de emoção ou entonação customizável.
Os arquivos de áudio têm marca d'água?
Sim. Cada arquivo gerado contém uma marca d'água inaudível que identifica o conteúdo como fala sintética. Isso ajuda a distinguir o áudio gerado pela API de gravações humanas, mantendo a transparência sobre a origem do conteúdo auditivo.
Como reiniciar minha chave API?
Acesse a página /get-api-key/ e emita uma nova chave. A chave antiga é invalidada imediatamente ao gerar a nova. Isso é útil se você suspeitar que a chave foi exposta ou deseja resetar o acesso à API.
A API suporta narração em tempo real?
Não. A narração não é em tempo real; há um atraso de processamento. Textos curtos levam alguns segundos, enquanto textos longos são gerados em velocidade aproximadamente real. As requisições são processadas em fila, podendo haver espera sob carga.
Primeira solicitação
curl
curl https://api.st650.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.mp3Python (openai)
from openai import OpenAI
client = OpenAI(base_url="https://api.st650.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.st650.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 | |
|---|---|
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 iniciar a narração de histórias infantis, acesse a página /get-api-key/ e registre-se com o Google ou e-mail. A chave de acesso é gerada automaticamente e exibida junto com seu saldo e crédito de teste.
Utilize a chave no cabeçalho de autorização para garantir que suas requisições sejam reconhecidas pelo sistema.
Como obter sua chave de acesso
O registro é feito diretamente no site st650.info. Ao usar o Google, você recebe US$ 0,50 de crédito para testar a API por 7 dias. Contas criadas com e-mail e senha não possuem crédito inicial.
Após o login, a página exibe sua chave única, o saldo atual e o histórico de uso, facilitando o controle de custos para projetos educacionais.
- Registro via Google ou e-mail/senha
- Crédito de teste de US$ 0,50 para contas Google
- Exibição imediata da chave e saldo
Formato da chave Bearer
Inclua a chave no cabeçalho HTTP da seguinte forma: Authorization: Bearer tts-.... O formato segue o padrão Bearer, compatível com SDKs oficiais.
Uma única chave ativa por conta garante simplicidade na integração com bibliotecas de Python ou Node.js.
Reivindicar nova chave se necessário
Você pode emitir uma nova chave a qualquer momento na interface da conta. A chave anterior é encerrada imediatamente ao gerar a nova, garantindo segurança.
Essa função é útil caso a chave seja exposta ou para fins de organização entre diferentes turmas ou projetos pedagógicos.
Endpoint principal de narração
O endpoint principal /v1/audio/speech é o núcleo da API. Você envia o texto da história e recebe o arquivo de áudio pronto para uso pedagógico. A estrutura segue o padrão OpenAI, facilitando a integração em ambientes educacionais.
Método POST para /v1/audio/speech
Envie requisições HTTPS POST para https://api.st650.info/v1/audio/speech. Este endpoint processa o texto e retorna o áudio sintetizado.
Corpo da requisição JSON
O corpo deve ser um objeto JSON contendo model (tts-1 ou tts-1-hd), input (texto até 4096 caracteres), voice (um dos 8 presets) e response_format.
model: "tts-1" ou "tts-1-hd"input: texto da históriavoice: nome do preset (ex: aria, nova)response_format: mp3, wav, opus, flac ou pcm
Resposta com arquivo de áudio
A resposta contém o arquivo de áudio binário. Textos longos devem ser divididos em partes de até 4096 caracteres e os arquivos de áudio resultantes unidos.
Parâmetros essenciais
A API utiliza dois modelos idênticos em motor de síntese: "tts-1" e "tts-1-hd". Ambos usam o mesmo motor e têm o mesmo preço.
Modelo: tts-1 ou tts-1-hd
O campo model aceita apenas os valores "tts-1" ou "tts-1-hd". Não há diferença técnica no resultado final do áudio; a escolha é neutra em termos de preço e qualidade vocal.
Input: texto até 4096 caracteres
Cada requisição aceita no máximo 4.096 caracteres, incluindo espaços e pontuação. Para histórias infantis mais longas, é necessário dividir o texto em partes menores e concatenar os arquivos de áudio resultantes.
- Espaços e pontuação contam como caracteres.
Voice: escolha entre 8 presets
O campo voice exige um dos oito presets disponíveis. Para narrativas educativas, vozes como "sage" (calma e instrucional) ou "aria" (narradora clara) são adequadas para leitura de textos didáticos.
Todos os 8 vozes conseguem falar os 23 idiomas suportados, permitindo a mesma voz para diferentes contos em línguas distintas.
- aria: narradora clara e quente
- sage: calma e instrucional
- nova: brilhante e animada
- luna: suave, ideal para histórias
Formatos de áudio suportados
A API retorna arquivos de áudio nos formatos mp3, wav, opus, flac e pcm. A escolha do formato depende do uso pedagógico: mp3 é leve para web, enquanto wav preserva a integridade para edições. Todos os formatos mantêm a qualidade do modelo selecionado.
O campo response_format aceita essas opções. Para aplicativos escolares ou leitura rápida, mp3 é eficiente. Para análises acústicas ou arquivos armazenados sem compressão, wav é ideal. A escolha não altera a voz, apenas o container do arquivo.
MP3 para web e mobile
O formato MP3 é comprimido e leve, eficiente para web e mobile.
WAV para alta qualidade
O formato WAV oferece áudio não comprimido, preservando todos os detalhes da síntese. É recomendado para educadores que desejam editar o áudio em softwares de produção ou arquivar narrações sem compressão.
OPUS, FLAC e PCM disponíveis
Além de MP3 e WAV, a API suerta OPUS (alta eficiência), FLAC (compressão sem perda) e PCM (bruto). Esses formatos atendem a necessidades específicas de armazenamento ou processamento posterior, permitindo que desenvolvedores escolham entre tamanho de arquivo e qualidade absoluta.
Controle de velocidade e idioma
O parâmetro speed aceita valores de 0.25 a 4.0, permitindo ajustar a cadência da narração conforme o contexto pedagógico. Textos mais lentos (próximos de 0.25) favorecem a compreensão de ouvintes iniciantes ou crianças, enquanto velocidades mais altas aceleram a leitura sem perder a clareza.
Ajuste de velocidade (0.25–4.0)
Valores padrão mantêm uma cadência natural. Ajustes extremos podem alterar a entonação, mas preservam a voz selecionada. Use velocidades moderadas para histórias contínuas e mais lentas para exercícios de ditado ou pronúncia.
- 0.25: narração lenta, ideal para alfabetização
- 1.0: velocidade padrão, natural
- 2.0+: leitura rápida, revisões
Definição explícita de idioma
Especifique o idioma via código ISO para garantir a pronúncia correta, especialmente em textos curtos ou ambíguos. O suporte inclui 23 idiomas, como português, espanhol e inglês.
- Código ISO recomendado para precisão
- Suporte a múltiplos idiomas na mesma API
Detecção automática de script
Se o campo language não for definido, o sistema infere o idioma com base no script do texto. Textos em latim são tratados como inglês por padrão; defina language explicitamente para textos em português ou outros idiomas latinos para evitar erros de pronúncia.

Uso com SDK oficial
Para utilizar o SDK da OpenAI, basta alterar o base_url para https://api.st650.info/v1 e fornecer a chave API gerada em seu painel. A estrutura do corpo da requisição permanece idêntica à da API de speech da OpenAI, garantindo que bibliotecas padrão funcionem sem adaptações complexas.
Configuração do base_url
O SDK utiliza https://api.st650.info/v1 como endpoint base. A autenticação é feita via cabeçalho Authorization: Bearer sua-chave-aqui, onde a chave é iniciada por tts-.
Exemplo com biblioteca OpenAI
Instale a biblioteca openai e configure o client com a URL alternativa. O método Audio.speech.create envia o texto para síntese, retornando o áudio conforme especificado nos parâmetros de voz e formato.
- Configure
base_urlparahttps://api.st650.info/v1 - Use o método padrão
Audio.speech.create - A chave deve ser válida e ativa no painel
Compatibilidade com Python e Node
As bibliotecas oficiais em Python e Node.js suportam essa configuração nativamente.
Limites e cotas
Entender os limites de uso é essencial para planejar a geração de áudios em sala de aula ou em projetos pedagógicos contínuos. A API impõe uma taxa de segurança que varia conforme o status da conta e o volume de solicitações simultâneas.
60 requisições por minuto
O limite padrão para chaves ativas é de 60 requisições por minuto. Isso permite um fluxo constante de geração de áudio, desde que o volume de texto seja gerenciado dentro da cota de caracteres.
Limite inicial de 10 req/min
Novas contas começam com uma taxa reduzida de 10 requisições por minuto. Esse limite é aplicado antes da primeira recarga de saldo, servindo como uma fase inicial de teste controlado.
Gestão de fila de processamento
As solicitações são processadas sequencialmente. Em momentos de alta demanda, sua requisição pode entrar em uma fila de espera antes de começar a síntese. Textos longos geram arquivos maiores, o que pode aumentar o tempo total de entrega.
Tratamento de erros e casos
Entender como a API lida com falhas e limites é essencial para a estabilidade dos seus projetos educacionais. A API devolve o áudio gerado diretamente na resposta, sem armazenamento persistente dos arquivos de áudio, garantindo que o texto seja usado exclusivamente para a síntese.
Este guia detalha o comportamento de cobrança, o tratamento de erros e a estratégia recomendada para textos extensos, comuns em narrativas de histórias infantis.
Retorno em caso de falha
Se a síntese falhar, a requisição é retornada sem custo. A API não cobra por tentativas que não resultam em arquivo de áudio, protegendo seu saldo de erros técnicos ou de formato.
Recomendamos implementar lógica de retry simples para requisições que falham rapidamente, mas evite loops infinitos para não sobrecarregar a fila de processamento.
Cobrança em solicitações bem-sucedidas
A cobrança é aplicada apenas quando o áudio é gerado com sucesso. O custo é de $0,01 por 1.000 caracteres, incluindo espaços e pontuação.
Use a página de dashboard para monitorar o saldo restante e garantir que há créditos suficientes para as narrações planejadas.
Manuseio de textos longos
O limite de entrada é de 4.096 caracteres por requisição. Para histórias infantis mais longas, divida o texto em partes menores e junte os arquivos de áudio resultantes.
Essa abordagem garante que cada fragmento seja processado dentro dos limites técnicos, mantendo a qualidade e a consistência da voz selecionada.
Monitore a fila de processamento, pois requisições podem esperar se houver alta demanda, especialmente em horários de pico.
- Texto máximo: 4.096 caracteres por chamada.
- Divida textos longos manualmente ou via script.
- Junte os arquivos de áudio finalizados.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. A pronúncia é consistente, pois a voz não muda de sotaque dependendo do idioma.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
