Documentação da API de Texto para Fala para Startups

Por Equipe editorial Narrador Fit · Atualizado 2026-11-19

Esta documentação técnica descreve a API de texto para fala (TTS) projetada para startups de fitness e meditação que precisam de narrações claras e consistentes em 23 idiomas. Aqui você encontra especificações precisas para integrar a geração de áudio ao seu backend, com foco em simplicidade e eficiência.

Utilize os endpoints descritos para enviar texto e receber arquivos de áudio em formatos como MP3, WAV ou OPUS. A integração é compatível com o SDK oficial da OpenAI, exigindo apenas a configuração do base_url para usar as bibliotecas oficiais. Este guia cobre autenticação, parâmetros de requisição, limites de taxa e tratamento de erros para implementação robusta.

Documentação da API de Texto para Fala para Startups

Perguntas frequentes

Qual é o endpoint principal?

O endpoint principal é POST https://api.tk89.info/v1/audio/speech. Ele aceita um corpo JSON com os parâmetros de síntese, como modelo, voz e texto de entrada, retornando o arquivo de áudio gerado conforme solicitado pelo cliente.

Como autenticar na API?

A autenticação é feita via cabeçalho Authorization: Bearer tts-... com a chave única da conta. Uma nova chave invalida a anterior imediatamente. O limite é de 60 requisições por minuto por chave ativa.

Posso usar o SDK do OpenAI?

Sim. A API segue o mesmo formato de requisição do endpoint de fala da OpenAI. Basta alterar o base_url para https://api.tk89.info/v1 e utilizar sua chave de API para integrar as bibliotecas oficiais do SDK.

Qual o tamanho máximo do texto?

O campo input aceita até 4096 caracteres por requisição. Para textos longos, deve-se dividir o conteúdo em partes dentro desse limite e juntar os arquivos de áudio resultantes para gerar a narração completa.

O que é o campo response_format?

Este campo define o formato do arquivo de áudio retornado. As opções disponíveis são mp3, wav, opus, flac e pcm. A escolha afeta apenas o container do áudio, não a qualidade da síntese.

Como funciona a velocidade (speed)?

O parâmetro speed ajusta a velocidade da fala entre 0.25 e 4.0. O valor padrão é 1.0. Alterações na velocidade não mudam o tom ou a entonação da voz selecionada, apenas a taxa de fala.

O que acontece se o limite for excedido?

O limite é de 60 requisições por minuto por chave. Como as requisições são executadas sequencialmente sob carga, pode haver espera até que a taxa de transmissão seja respeitada e a síntese seja concluída.

A API retorna áudio em streaming?

Não. A API retorna o arquivo de áudio completo após o processamento. Não há suporte para streaming, WebSocket ou áudio parcial em tempo real. O cliente deve aguardar a conclusão da geração do arquivo.

Primeira solicitação

curl

curl https://api.tk89.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.tk89.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.tk89.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

A autenticação na API Narrador Fit utiliza o padrão Bearer Token. Cada conta possui uma única chave ativa que deve ser enviada no cabeçalho HTTP de todas as requisições. A validação ocorre no gateway, garantindo que apenas credenciais válidas acessem os endpoints de síntese.

Cabeçalho Authorization

Cabeçalho Authorization

O cabeçalho obrigatório é Authorization. O valor deve ser exatamente Bearer <sua-chave-api>. Não utilize outros esquemas de autenticação; a API espera estritamente o prefixo Bearer seguido pelo token gerado na sua conta.

Formato da chave Bearer

Formato da chave Bearer

As chaves começam com o prefixo tts-. Elas são únicas por conta e funcionam como credenciais de acesso direto ao serviço. Não há necessidade de refresh tokens ou assinaturas JWT complexas.

Geração de nova chave

Você pode emitir uma nova chave a qualquer momento diretamente no painel da sua conta. Ao gerar uma nova chave, a anterior é invalidada imediatamente. Isso é útil para revogar acesso rapidamente em caso de comprometimento ou migração de infraestrutura.

Endpoints principais

Ilustração de onda sonora para: Endpoints principais

A API oferece três endpoints principais para integração. O endpoint principal gera áudio a partir de texto, enquanto os outros dois listam vozes disponíveis e modelos de síntese.

Tudo segue o padrão OpenAI, facilitando a adaptação para startups de fitness e meditação que precisam de narrações consistentes em 23 idiomas.

POST /v1/audio/speech

Envia texto e recebe arquivo de áudio. Suporta até 4096 caracteres por requisição. Retorna os formatos selecionados.

  • Endpoint principal de síntese

GET /v1/voices

Lista todas as vozes disponíveis, idiomas e formatos suportados. Útil para validar configurações antes de enviar requisições de áudio.

GET /v1/models

Retorna os modelos disponíveis (tts-1 e tts-1-hd). Ambos utilizam o mesmo motor de síntese e preço.

Exemplo com Curl

Ilustração de onda sonora para: Exemplo com Curl

O endpoint POST /v1/audio/speech aceita texto e retorna áudio sintetizado. Este exemplo demonstra a chamada mínima necessária para gerar uma narração fitness em inglês.

Comando básico

Use o comando abaixo para enviar uma requisição simples. Substitua SEU_TOKEN pela chave da sua conta no cabeçalho Authorization.

  • curl -X POST https://api.tk89.info/v1/audio/speech \
  • -H "Authorization: Bearer SEU_TOKEN" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Start your workout now", "voice": "nova"}'

Parâmetros de input

O campo input aceita até 4096 caracteres. Espaços e pontuação contam como caracteres. Para textos longos, divida o conteúdo e junte os arquivos de áudio resultantes.

  • "model": "tts-1" ou "tts-1-hd"
  • "voice": "nova" (exemplo: voz feminina, energética)
  • "input": "Sua frase aqui" (máx. 4096 chars)

Resposta de áudio

A resposta contém o arquivo de áudio binário no formato solicitado. Por padrão, o formato é mp3. Guarde o arquivo localmente ou processe-o diretamente na sua aplicação.

Integração com SDK OpenAI

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

O SDK oficial da OpenAI funciona diretamente com a Narrador Fit ao ajustar a URL base. Basta alterar a URL base para apontar para a API tk89.info, mantendo a estrutura de chamadas padrão.

Configuração do base_url

Defina o atributo base_url da instância do cliente para https://api.tk89.info/v1. Isso redireciona todas as requisições para o endpoint correto sem necessidade de reescrever a lógica de chamadas.

Uso da biblioteca oficial

Utilize a biblioteca openai padrão em Python ou JavaScript. Passe sua chave API (tts-...) no cabeçalho de autenticação. O formato de payload permanece idêntico ao esperado pelo endpoint de speech original.

  • Instale a biblioteca oficial mais recente.
  • Não requer adaptações de estrutura JSON.

Compatibilidade de métodos

O método Audio.speech.create funciona nativamente. Todos os campos suportados (model, voice, input) são mapeados corretamente. Não é necessário usar a biblioteca customizada da Narrador Fit.

Parâmetros de requisição

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

A API aceita texto bruto como entrada para geração de fala. O campo input suporta até 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos longos, é necessário dividir o conteúdo em partes menores e juntar os arquivos de áudio resultantes.

O campo voice define a timbre da voz sintetizada. Há 8 opções predefinidas, como aria para narrativas ou atlas para notícias. O campo response_format determina o formato do arquivo de áudio retornado, permitindo escolhas como mp3, wav, opus, flac ou pcm.

Campo input (texto)

Envie o texto a ser convertido diretamente no campo input. O limite máximo é de 4096 caracteres por solicitação. Se o texto exceder esse limite, divida-o em fragmentos e processe-os sequencialmente, unindo os arquivos de áudio gerados para criar a faixa completa.

O campo language é opcional e pode ser usado para forçar um idioma específico quando o texto estiver em script latino, evitando a detecção automática padrão para inglês.

Campo voice (8 opções)

Selecione uma das 8 vozes disponíveis para definir o estilo da narração. As opções incluem aria, nova, luna, sage, felix, milo, atlas e orion. Cada voz possui uma característica distinta, adequada para diferentes contextos de fitness ou meditação.

Todas as vozes podem falar em qualquer um dos 23 idiomas suportados. Não é necessário selecionar uma voz específica para cada idioma; o modelo adapta-se automaticamente.

  • aria: voz feminina, clara e quente
  • nova: voz brilhante e energética
  • luna: suave, ideal para storytelling
  • sage: calma e instrucional
  • felix: energética, para promoções
  • milo: amigável e conversacional
  • atlas: neutra, estilo noticiário
  • orion: profunda, estilo documentário

Campo response_format

O campo response_format permite especificar o formato do arquivo de áudio retornado na resposta da API. As opções disponíveis são mp3, wav, opus, flac e pcm.

Escolha o formato que melhor se integra ao seu pipeline de áudio. MP3 e WAV são amplamente suportados, enquanto OPUS e FLAC oferecem compressão eficiente com qualidade preservada, e PCM fornece áudio bruto não comprimido.

Parâmetros de requisição

Limites e Erros

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

A API impõe limites rigorosos para garantir estabilidade. Se você exceder a cota de 60 requisições por minuto, receberá o status 429. Para contas novas, o limite inicial é mais restrito (10 requisições/min) até o primeiro depósito.

O campo input aceita no máximo 4096 caracteres por chamada. Textos longos devem ser divididos e unidos pelo cliente. Cada caractere, incluindo espaços, conta para o limite e para a cobrança.

429 Too Many Requests

Ao atingir o limite de 60 req/min (ou 10/min no início), a API retorna 429. Implemente retry com backoff exponencial para evitar bloqueios desnecessários durante picos de geração de áudio para seus apps de fitness.

  • Limite padrão: 60 req/min por chave.
  • Limite inicial: 10 req/min até primeiro top-up.
  • Retorne status 429 com cabeçalho Retry-After.

Limite de 4096 caracteres

Cada requisição POST é limitada a 4096 caracteres de entrada. Para narrações de meditação longas, divida o texto manualmente, envie as partes sequencialmente e junte os arquivos de áudio resultantes no lado do cliente.

  • Máximo: 4096 chars por request.
  • Espaços e pontuação contam como caracteres.
  • Divisão manual necessária para textos longos.

Códigos de erro comuns

Além do 429, erros 400 indicam parâmetros inválidos (ex: voice inexistente). Erros 500 são temporários; se a síntese falhar, o crédito é devolvido integralmente. Monitore os logs de status para auditoria.

O formato de resposta de erro segue o padrão JSON padrão, facilitando o tratamento programático em qualquer stack moderna sem dependências externas complexas.

  • 400: Parâmetros inválidos ou formato incorreto.
  • 401: Chave API inválida ou expirada.
  • 429: Limite de taxa excedido.
  • 500: Erro interno, crédito devolvido se falhar.

Formatos de áudio

Ilustração de onda sonora para: Formatos de áudio

A escolha do formato de áudio impacta diretamente a largura de banda e a compatibilidade do player na sua aplicação fitness ou de meditação. A API oferece cinco formatos nativos.

MP3 e WAV

O MP3 é o padrão para a maioria dos players web e móveis, oferecendo compressão eficiente sem perda perceptível significativa para vozes narradas. O WAV fornece áudio PCM não comprimido, ideal para edições pós-produção ou arquivos que exigem latência zero de decodificação.

OPUS e FLAC

O OPUS é um formato de áudio eficiente. O FLAC oferece compressão sem perda, ideal para arquivamento de alta fidelidade onde o espaço de disco é menos crítico que a integridade do sinal.

PCM puro

O formato PCM retorna o áudio bruto, sem cabeçalhos de container. É útil para pipelines de processamento de sinal ou integração com sistemas de áudio nativos que gerenciam a formatação internamente.

Tratamento de erros

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

A API retorna status HTTP padrão para indicar falhas. Se a síntese falhar, o crédito é devolvido integralmente, garantindo que você não pague por áudio inválido.

Monitore os logs de status para auditoria. Requests bem-sucedidos retornam o arquivo de áudio; erros retornam detalhes para depuração rápida.

Falha de síntese

Se o motor não conseguir gerar áudio (ex: input inválido ou timeout), a resposta não conterá o arquivo binário. Verifique os códigos de erro retornados no corpo da resposta JSON.

A falha não consome crédito. O sistema identifica automaticamente quando o processamento foi interrompido antes da geração final.

Retorno de crédito

Créditos não são descontados para requisições que falham. O saldo da sua conta permanece inalterado se a síntese não for concluída com sucesso.

Isso se aplica a erros internos do servidor ou timeouts. Solicitações processadas com sucesso, mesmo com áudio gerado, são cobradas normalmente.

Log de status

Metadados de tempo, caracteres e status são mantidos para faturamento. Use esses dados para monitorar a saúde da sua integração em tempo real.

Registre os status codes (200, 429, 500) para auditoria e ajuste de latência, especialmente útil para apps de fitness que exigem resposta rápida.

  • Código 200: Sucesso, áudio incluído.
  • Código 429: Limite de taxa excedido.
  • Código 500: Erro interno do servidor.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Requisições falhas são gratuitas e o crédito é estornado automaticamente.

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. Tether (USDT)
  3. curl documentation
  4. Node.js documentation
  5. MDN: Web Speech API
  6. IETF RFC 7845: Ogg Opus
  7. openai-python on GitHub
  8. Python documentation
  9. LibriTTS-R corpus (OpenSLR 141)
  10. LibriVox public-domain audiobooks
  11. Creative Commons Attribution 4.0
  12. TRON developer hub: TRC-20

Mais neste site