Como usar a API de Texto para Fala na Prática

Por Equipe editorial NarraTuri · Atualizado 2026-11-19

Esta documentação técnica explica como integrar nossa API de texto para fala em projetos de audioguias, museus e conteúdos turísticos. Você verá exemplos práticos de cURL, integração com SDKs e configuração de vozes, sem necessidade de programação avançada.

Aqui você encontrará tudo para gerar áudios de qualidade: limites de uso, formatos disponíveis, tratamento de erros e segurança da chave. Ideal para criadores que querem transformar roteiros em narração real para visitantes ou vídeos, com controle total sobre idioma e velocidade.

Como usar a API de Texto para Fala na Prática

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.mp3

Python (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
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

Obtenha sua chave de API

Ilustração de onda sonora para: 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

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

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

Ilustração de onda sonora para: 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-hd
  • voice: por exemplo, 'nova' ou 'atlas'
  • input: seu texto narrado
  • response_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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

Limites e cotas

Tratamento de erros

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

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. FFmpeg documentation
  3. TRON developer hub: TRC-20
  4. ISO 639 language codes
  5. LibriVox public-domain audiobooks
  6. MDN: Web Speech API
  7. Creative Commons Attribution 4.0
  8. Node.js documentation
  9. openai-node on GitHub
  10. OpenAI API reference: create speech
  11. openai-python on GitHub
  12. Tether (USDT)

Mais neste site