Perguntas frequentes
Qual a estrutura do JSON de entrada?
Envie um POST para /v1/audio/speech com o campo input (texto até 4096 caracteres), model (tts-1 ou tts-1-hd), voice (um dos 8 presets) e response_format (mp3, wav, opus, flac ou pcm). O campo speed é opcional (0.25–4.0). A autenticação usa o cabeçalho Authorization: Bearer sua-chave-api.
Posso enviar textos maiores que 4096 caracteres?
Não. Cada requisição aceita no máximo 4096 caracteres. Para textos longos, divida o roteiro em partes menores e envie várias requisições. Depois, você deve juntar os arquivos de áudio gerados para criar o arquivo final completo.
Como especificar um idioma específico?
Use o campo language com o código ISO do idioma desejado. Se não for informado, o sistema tenta adivinhar pelo script; textos em latinos padrão para inglês. Para outros idiomas em latim, defina o campo explicitamente para evitar erros.
O SDK da OpenAI funciona perfeitamente?
Sim, pois a API segue a mesma estrutura de requisição. Basta alterar o base_url para https://api.talkbet.info/v1 e usar sua chave NarraTuri. As SDKs oficiais da OpenAI funcionam alterando apenas a URL base.
Quais formatos de áudio são suportados?
Você pode escolher entre mp3, wav, opus, flac e pcm no campo response_format. O mp3 é um dos formatos disponíveis. Escolha wav ou flac para áudio sem compressão, ou opus para arquivos menores.
O que fazer se receber um erro 429?
Isso indica que você excedeu o limite de 60 requisições por minuto. Aguarde até que o contador reinicie. Se estiver no início, o limite é de 10 requisições por minuto. Implemente uma lógica de retry com backoff para gerenciar a fila.
A velocidade afeta o preço?
Não. O preço é fixo em $10 por 1 milhão de caracteres, independentemente da velocidade configurada. O custo é baseado apenas na quantidade de caracteres do campo input, incluindo espaços e pontuação, enviada na requisição.
Posso misturar vozes no mesmo pedido?
Não. Cada requisição aceita apenas uma voz especificada no campo voice. Para usar vozes diferentes, envie múltiplas requisições, uma para cada trecho com sua voz específica, e depois junte os arquivos de áudio resultantes.
Como invalidar uma chave antiga?
Basta emitir uma nova chave na sua conta. A nova chave entra em vigor imediatamente e a anterior é desativada no mesmo instante. Você pode fazer isso quantas vezes precisar para garantir a segurança do seu acesso.
A API retorna metadados do áudio?
Não. A resposta contém apenas o arquivo de áudio binário. Os metadados de uso, como tempo, caracteres consumidos e status, são mantidos internamente para faturamento e podem ser consultados no painel da sua conta, não na resposta da API.
Há suporte para SSML?
Não. A API aceita apenas texto simples no campo input. Não há suporte para marcações SSML, dicionários de fonemas ou controle de pronúncia personalizado. A entonação é gerenciada automaticamente pelo modelo de síntese baseado em vozes licenciadas.
Posso usar a API em aplicações móveis?
Sim, você pode chamar a API diretamente de qualquer aplicativo móvel usando HTTP. Não existe um SDK específico para mobile, mas o uso via HTTP é suportado. Basta proteger sua chave de API adequadamente.
O que acontece em caso de queda?
Não oferecemos garantia de uptime ou SLA. Se houver indisponibilidade, o serviço pode ficar temporariamente inacessível. Se a síntese falhar, o valor é devolvido integralmente. Para suporte, entre em contato apenas por e-mail, pois não temos chat ou telefone.
Como rastrear o uso de caracteres?
Acompanhe seu saldo e consumo na página da sua conta após o login. O sistema registra tempo, caracteres e status para faturamento. Você verá o saldo restante e o histórico de uso, mas não há endpoint dedicado para métricas em tempo real.
Primeira solicitação
curl
curl https://api.talkbet.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.talkbet.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.talkbet.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 |
Obtenha sua chave de API
Para começar a usar a NarraTuri em seus projetos turísticos ou museus, você precisa de uma chave de API. A criação da conta é rápida: acesse a página /get-api-key/ e faça login com sua conta Google ou crie um perfil com e-mail e senha.
Uma vez registrado, você terá acesso imediato ao painel da sua conta. Não é necessário cartão de crédito para iniciar, apenas o cadastro simples para gerar seu identificador único de acesso.
Crie uma conta no site
O registro leva menos de um minuto. Você pode usar o login com Google para agilidade ou preferir o método tradicional com e-mail e senha. Essa conta é específica para o site talkbet.info e permite o acesso ao painel de controle.
- Acesso via Google ou e-mail/senha
- Conta específica para talkbet.info
Acesse a página de configuração
Após o login, navegue até a página de configuração da API. É aqui que você visualiza todas as informações necessárias para integrar o serviço aos seus roteiros de áudio. O painel exibe seu saldo, créditos de teste e o histórico de uso.
- Visualização de saldo e créditos
- Histórico de caracteres utilizados
Copie sua chave única
Sua chave de API é um token alfanumérico que inicia com 'tts-'. Copie essa string e guarde-a com segurança, pois ela é o único meio de autenticação para suas requisições. Você pode gerar uma nova chave a qualquer momento, o que invalida a anterior instantaneamente.
- Formato: tts-...
- Invalidação imediata ao gerar nova chave
Primeira solicitação com cURL
Testar a API é rápido e direto. Use cURL para enviar texto e receber áudio, validando o funcionamento antes de qualquer integração mais complexa.
O processo envolve enviar um POST JSON para o endpoint correto. Você recebe o arquivo de áudio pronto para uso, sem necessidade de processamento adicional.
Exemplo de comando básico
Copie o comando abaixo, substituindo SUA-CHAVE-AQUI pela sua chave real. O comando envia o texto 'Olá, bem-vindo ao museu' para ser convertido em fala.
A resposta será um arquivo de áudio binário, que você pode salvar no seu disco local.
- Substitua a chave de autenticação
- Salve o resultado em um arquivo local
- Teste com textos curtos primeiro
Estrutura JSON do corpo
O corpo da requisição deve ser enviado como JSON. O campo model aceita tts-1 ou tts-1-hd, ambos com o mesmo motor e preço.
Especifique o voice desejado entre as 8 opções disponíveis. O campo input contém o texto a ser narrado, respeitando o limite de 4096 caracteres.
model: tts-1 ou tts-1-hdvoice: por exemplo, 'nova' ou 'atlas'input: seu texto narradoresponse_format: mp3, wav, opus, flac ou pcm
Resposta com arquivo de áudio
A API retorna o arquivo de áudio diretamente no corpo da resposta HTTP. Não há necessidade de fazer outra chamada para baixar o arquivo.
Se a síntese falhar, o crédito é devolvido integralmente. Para textos longos, você deve dividir o texto em partes e juntar os arquivos gerados.
- Áudio retornado diretamente na resposta
- Falhas devolvem o crédito
- Textos longos exigem divisão manual
Integração com SDK OpenAI
A API NarraTuri segue o mesmo formato de payload da OpenAI, permitindo que você reutilize bibliotecas oficiais alterando a URL base. Basta configurar o base_url para https://api.talkbet.info/v1 e inserir sua chave de API no cabeçalho de autenticação.
Alterar base_url para a API
Aponte o cliente para o endpoint correto. Todas as requisições POST para /audio/speech serão processadas pelos nossos servidores de TTS, mantendo a estrutura de resposta esperada.
Usar o mesmo formato de payload
Envie os parâmetros model, input, voice e response_format exatamente como a documentação padrão exige. O sistema aceita tts-1 ou tts-1-hd, retornando o arquivo de áudio sintetizado diretamente no corpo da resposta.
Compatibilidade com bibliotecas oficiais
Utilize o SDK oficial da OpenAI (Python, Node.js, etc.) alterando apenas a URL base. Isso simplifica a integração para criadores de conteúdo que já conhecem o ecossistema, sem necessidade de SDKs proprietários adicionais.
Formatos de áudio disponíveis
Escolha o formato que melhor se adapta à sua aplicação. O MP3 é ideal para players web e apps móveis, garantindo compatibilidade universal e arquivos leves. O WAV oferece áudio sem compressão, perfeito para edições ou arquivos locais. Já o FLAC preserva a qualidade original sem perda de dados, sendo uma opção para arquivamento.
MP3 para web e mobile
O formato MP3 é o mais versátil para distribuição. Ele equilibra qualidade sonora e tamanho reduzido, facilitando o carregamento rápido em dispositivos móveis e navegadores modernos.
WAV para alta qualidade
Utilize o WAV quando precisar de áudio não comprimido. É excelente para processos de pós-produção ou quando a fidelidade sonora é prioritária em arquivos locais.
FLAC para arquivamento sem perda
O formato FLAC oferece compressão sem perda de qualidade. Ideal para guardar suas produções de áudio com a máxima fidelidade possível, pronto para uso futuro.
Limites e cotas
Para garantir que a geração de áudio flua sem interrupções, a API impõe limites claros de uso. Entender essas cotas é essencial para quem está integrando narração em audioguias ou plataformas de turismo sem precisar de ajustes complexos de infraestrutura.
O sistema controla tanto a velocidade de envio quanto o tamanho do texto por chamada. Isso evita gargalos e garante que você receba o arquivo de áudio de forma previsível, seja para um museu ou para um vídeo explicativo.
60 requisições por minuto
Após realizar o primeiro depósito, você tem permissão para enviar até 60 requisições por minuto. Esse limite é suficiente para a maioria dos casos de uso.
Se o volume de solicitações exceder essa capacidade, as requisições adicionais podem ser processadas com algum atraso, pois elas entram em uma fila de espera até que haja disponibilidade.
10 requisições antes do primeiro depósito
Contas recém-criadas começam com uma cota mais restrita de 10 requisições por minuto. Essa configuração inicial permite que você teste a API e valide a qualidade das vozes.
Para aumentar esse limite para 60 requisições por minuto, basta realizar seu primeiro depósito via USDT (TRC-20). O crédito é adicionado automaticamente e a cota de uso é atualizada em poucos minutos.
Limite de 4096 caracteres por pedido
Cada solicitação pode conter até 4096 caracteres, incluindo espaços e pontuação. Para textos mais longos, como roteiros completos de audioguias, você deve dividir o texto em partes menores e unir os arquivos de áudio gerados.
Essa abordagem garante que a síntese seja realizada com eficiência. Lembre-se de que o tempo de geração é aproximadamente equivalente ao tempo real da fala, então textos muito longos podem levar alguns minutos para serem processados.

Tratamento de erros
A API retorna códigos HTTP claros para indicar o sucesso ou o motivo de falhas. Use esses códigos para direcionar o tratamento automático no seu sistema de audioguias ou produção de conteúdo.
Entender a resposta ajuda a evitar erros recorrentes e garante que a narração seja entregue sem interrupções desnecessárias para seus visitantes ou espectadores.
Códigos de status HTTP
Respostas 200 indicam sucesso. Códigos 4xx sinalizam erros de solicitação, como chave inválida ou limite excedido. Códigos 5xx indicam problemas temporários no serviço.
Verifique sempre o corpo da resposta para detalhes específicos do erro.
- 200: Sucesso
- 401: Chave inválida
- 429: Limite de requisições excedido
Mensagens de erro comuns
Mensagens detalhadas explicam se o texto excedeu 4096 caracteres ou se o formato JSON está incorreto. Ajuste os parâmetros conforme indicado para retentar.
Erros de validação impedem a geração até que o corpo da solicitação esteja correto.
Retorno de crédito em falha
Se a síntese falhar, o crédito é devolvido integralmente. Você não paga por áudios que não foram gerados com sucesso.
Isso garante que apenas o trabalho concluído seja cobrado, mantendo o custo previsível para seus projetos.
Parâmetros de voz e idioma
A API oferece oito vozes predefinidas, classificadas entre masculinas e femininas, projetadas para diferentes contextos narrativos. Você pode escolher entre vozes como Aria, com tom de narradora clara, ou Felix, mais energético para promoções, garantindo que o áudio se ajuste ao estilo do seu conteúdo turístico ou museológico.
O sistema detecta automaticamente o idioma pelo script do texto, mas o parâmetro language permite forçar a identificação. Isso é essencial para textos em línguas latinas que não sejam inglês, evitando erros de pronúncia. Se omitido, o padrão é inglês para textos em alfabeto latino.
Seleção de 8 vozes predefinidas
As vozes incluem Aria (narração clara), Nova (leve), Luna (histórias), Sage (instrucional), Felix (promo), Milo (conversacional), Atlas (neutro) e Orion (documentário). Todas suportam os 23 idiomas disponíveis.
Escolha a voz mais adequada ao tom do seu guia ou aplicativo, mantendo a qualidade e a clareza da narração sem necessidade de edição complexa.
- Aria: narradora clara e quente
- Nova: leve e otimista
- Luna: suave para histórias
- Sage: calma e instrucional
- Felix: energético e promocional
- Milo: amigável e conversacional
- Atlas: neutro e informativo
- Orion: profundo e documental
Definição de idioma ISO
O parâmetro language aceita códigos ISO opcionais. Se não especificado, o sistema tenta adivinhar pelo script. Para textos em português, espanhol ou outras línguas latinas fora do inglês, defina explicitamente o código para garantir a pronúncia correta.
Isso evita que o motor interprete erroneamente palavras similares ou acentos, garantindo que o áudio final soe natural para o público-alvo do seu conteúdo.
Ajuste de velocidade (0.25 a 4.0)
O parâmetro speed permite ajustar a velocidade da fala entre 0.25 (muito lento) e 4.0 (muito rápido). Isso é útil para adaptar o áudio a diferentes contextos, como audioguias em museus ou vídeos explicativos.
Ajustar a velocidade pode melhorar a compreensão em conteúdos técnicos ou tornar a narração mais dinâmica para públicos mais jovens.
Autenticação segura
Para que a API reconheça sua solicitação, inclua o cabeçalho Authorization: Bearer tts-sua-chave-aqui em todas as requisições POST. Essa autenticação simples garante que apenas sua conta possa utilizar os caracteres pagos e gerar áudios em seu nome.
Uso do cabeçalho Authorization
O cabeçalho deve ser enviado em cada chamada à endpoint v1/audio/speech. Sem ele, a API rejeita a solicitação com erro 401, indicando que a identidade do usuário não foi verificada.
- Sempre inclua no cabeçalho HTTP da requisição
- Funciona com curl, SDKs e bibliotecas HTTP padrão
Formato Bearer token
O valor deve ser exatamente Bearer tts-..., seguido pela chave única gerada no painel. Não adicione espaços extras ou aspas duplas ao redor da string completa.
Revogação imediata de chaves
Cada conta possui apenas uma chave ativa por vez. Ao gerar uma nova chave na página de configuração, a anterior deixa de funcionar imediatamente, garantindo segurança caso haja vazamento.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Sua conta é criada instantaneamente, pronta para gerar os primeiros áudios de narração turística.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
