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.mp3Python (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 | |
|---|---|
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
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
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
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
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
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
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
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.

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