Perguntas frequentes
O que é uma chave de API?
Sua chave de API é um token de autenticação único que inicia com 'tts-' e garante acesso à nossa API. Ela deve ser enviada no cabeçalho 'Authorization: Bearer' em cada requisição. Cada conta possui apenas uma chave ativa por vez, servindo como sua credencial principal para emitir e usar os serviços de síntese de voz.
Como obtenho minha chave?
Acesse a página /get-api-key/ e registre-se usando sua conta Google ou e-mail com senha. Após o login, o painel exibirá sua chave de API atual, o saldo disponível, o crédito de teste (se aplicável) e um exemplo de comando curl pronto para uso imediato na sua integração.
Posso emitir uma nova chave?
Sim, você pode emitir uma nova chave a qualquer momento diretamente pelo painel da sua conta. Isso é útil para renovar a segurança ou substituir uma chave comprometida, garantindo que você mantenha o controle total sobre o acesso aos seus serviços de texto para fala sem interrupções prolongadas.
A chave antiga para de funcionar?
Sim, assim que você emite uma nova chave, a chave anterior deixa de funcionar imediatamente. Isso garante que apenas a credencial mais recente seja válida para autenticação, proporcionando segurança instantânea sem necessidade de esperar por propagação de cache ou reinícios de serviço em servidores externos.
Qual o limite de caracteres por request?
Cada requisição pode conter até 4096 caracteres no campo 'input'. Para textos mais longos, você deve dividi-los em partes dentro desse limite e juntar os arquivos de áudio resultantes. Isso permite processar narrativas extensas mantendo a compatibilidade com a estrutura padrão da nossa API de síntese.
O que é base_url na integração?
O base_url é o endereço base para as chamadas da API. Para usar nossos SDKs, configure-o como 'https://api.yefersoncasino.net/v1'. Isso permite que bibliotecas padrão, como as do OpenAI, funcionem corretamente ao apontar para o endpoint correto de síntese de voz em nosso ambiente cloud.
O SDK OpenAI funciona com esta API?
Sim, o formato da requisição é idêntico ao endpoint de fala do OpenAI. Basta alterar o 'base_url' para 'https://api.yefersoncasino.net/v1' e usar sua chave de API NarraTTS Brasil. Isso permite integrar rapidamente seus projetos existentes sem necessidade de reescrever toda a lógica de conexão.
Quais formatos de áudio posso solicitar?
Você pode solicitar os formatos mp3, wav, opus, flac ou pcm através do campo 'response_format'. Escolha o formato que melhor se adapta ao seu fluxo de trabalho de edição ou publicação. Cada formato oferece diferentes equilíbrios entre qualidade de áudio e tamanho de arquivo para seus projetos.
O que acontece se a requisição falhar?
Se a síntese falhar, o valor é devolvido integralmente ao seu saldo. Você não paga pelas requisições que falharem; as bem-sucedidas são cobradas normalmente. Isso garante que você seja cobrado apenas pelo trabalho efetivamente concluído, protegendo seu orçamento contra erros temporários ou problemas de processamento.
Qual a taxa de requisição permitida?
O limite é de 60 requisições por minuto por chave. Antes da primeira recarga, o limite é de 10 requisições por minuto. Se houver alta demanda, as requisições são processadas em fila, o que pode aumentar levemente o tempo total de geração para textos longos.
Posso ajustar a velocidade da voz?
Sim, o campo 'speed' aceita valores entre 0.25 e 4.0. Isso permite acelerar ou desacelerar a narração conforme necessário para o ritmo do seu vídeo ou spot de rádio. Ajuste fino ajuda a sincronizar perfeitamente a fala com as imagens ou trilhas sonoras do seu projeto.
Como especifico o idioma no request?
Use o campo opcional 'language' com o código ISO do idioma desejado. Se não especificado, o sistema tenta adivinhar pelo script, assumindo inglês para texto latino. Para textos em outros idiomas com alfabeto latino, defina o idioma explicitamente para garantir a pronúncia correta e natural da voz.
O que é o modelo tts-1-hd?
O modelo 'tts-1-hd' utiliza o mesmo motor de síntese do 'tts-1', oferecendo a mesma qualidade de áudio base. Ambos têm o mesmo preço de $0.01 por mil caracteres. A escolha entre eles não impacta o custo. A velocidade de geração é aproximadamente a mesma para ambos.
Existe suporte para SSML?
Não, nossa API não oferece suporte para marcação SSML. Você envia texto simples e controla pausas e entonação principalmente através da seleção de voz e ajuste de velocidade. Para nuances específicas de pronúncia, você pode escrever foneticamente no campo de texto, já que não há dicionário de pronúncia customizado.
Primeira solicitação
curl
curl https://api.yefersoncasino.net/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.yefersoncasino.net/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.yefersoncasino.net/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 NarraTTS Brasil, acesse a página /get-api-key/ e registre-se com sua conta Google ou crie um login por e-mail e senha. Cada site mantém contas independentes, então seu acesso é específico para este domínio.
Registro no site
O registro é rápido: clique em "Sign in with Google" para uso imediato ou preencha o formulário padrão. Contas criadas com e-mail e senha não recebem crédito de teste inicial, enquanto as vinculadas ao Google ganham $0,50 de crédito válido por 7 dias para você testar a API sem compromisso.
- Suporte via Google ou email+senha
- Contas são independentes por site
- Crédito inicial apenas para login Google
Localização da chave
Após o login, a página do painel exibe claramente sua chave de API ativa, o saldo atual, os caracteres restantes e um exemplo de comando cURL pronto para uso. A chave segue o formato tts-... e é necessária para autenticar todas as suas requisições.
Emissão de nova chave
Você possui apenas uma chave ativa por conta. Se precisar revogar o acesso antigo, simplesmente emita uma nova chave no painel. A chave anterior deixa de funcionar imediatamente, garantindo que você tenha controle total sobre quem está acessando sua API TTS.
Primeira requisição com cURL
A forma mais direta de testar a API é via linha de comando. Você envia um texto e recebe o arquivo de áudio pronto para uso em seus vídeos ou spots.
Este guia mostra exatamente como estruturar sua primeira chamada, garantindo que você entenda os parâmetros mínimos necessários para gerar áudio com sucesso.
Comando básico POST
Use o método POST no endpoint https://api.yefersoncasino.net/v1/audio/speech. O corpo da requisição deve ser JSON, contendo o texto a ser convertido e a voz desejada.
A autenticação é feita via cabeçalho Authorization: Bearer sua_chave_aqui. Substitua sua_chave_aqui pela chave obtida na página de registro.
- Endpoint: POST /v1/audio/speech
- Cabeçalho: Authorization: Bearer <sua_chave>
- Conteúdo: application/json
Parâmetros essenciais
O campo model aceita tts-1 ou tts-1-hd, ambos com o mesmo motor de síntese. O campo input contém o texto, limitado a 4096 caracteres. O campo voice deve ser uma das 8 vozes disponíveis, como nova ou felix.
Você pode especificar o response_format (mp3, wav, opus, flac, pcm) e ajustar a speed entre 0.25 e 4.0. O idioma é opcional; se não fornecido, o sistema tenta adivinhar, mas para textos em português, defina language: pt.
Resposta de sucesso
Uma resposta 200 retorna o arquivo de áudio binário diretamente no corpo da resposta. Salve esse conteúdo em um arquivo com a extensão correspondente ao formato escolhido.
Se a requisição falhar, você receberá um código de erro JSON explicando o problema, como autenticação inválida ou limite de caracteres excedido. Requisições falhas não cobram caracteres.
Integração com SDK OpenAI
A API NarraTTS Brasil segue o formato de requisição do endpoint de fala da OpenAI, o que facilita muito a integração para criadores de conteúdo que já utilizam ferramentas baseadas nesse padrão. Você só precisa ajustar a URL base e usar sua chave de API personalizada.
Essa compatibilidade permite que você utilize bibliotecas oficiais sem precisar aprender uma nova estrutura de requisições, mantendo seus fluxos de trabalho de geração de narração para vídeos e spots de rádio simples e eficientes.
Alteração do base_url
Para conectar seu projeto à NarraTTS, altere o parâmetro base_url para https://api.yefersoncasino.net/v1. Isso direciona todas as chamadas para nossa infraestrutura de API, mantendo a mesma estrutura de payload que você já conhece.
Exemplo de código Python
Utilize o SDK da OpenAI (ou HTTP direto) com a URL ajustada. O código abaixo ilustra como enviar texto e receber o arquivo de áudio diretamente, pronto para ser inserido em seus vídeos ou campanhas publicitárias.
```python import openai client = openai.OpenAI(api_key='sua-chave-aqui', base_url='https://api.yefersoncasino.net/v1') with client.audio.speech.with_streaming_response.create( model='tts-1', voice='nova', input='Olá, este é um spot de rádio gerado via API.', response_format='mp3' ) as response: response.stream_to_file('spot.mp3') ```
bullets
Compatibilidade com SDKs oficiais
Os SDKs oficiais da OpenAI funcionam perfeitamente, pois a forma como estruturamos as requisições é idêntica. Isso significa que você não precisa criar integrações do zero ou lidar com formatos de resposta exóticos, economizando tempo na produção de seus conteúdos. Note que não oferecemos nosso próprio SDK.
Parâmetros de requisição
Configure sua requisição JSON definindo o modelo, a voz e o formato de saída. Esses parâmetros controlam a qualidade e o tipo do arquivo gerado, garantindo que o áudio se integre perfeitamente ao seu projeto de vídeo ou spot de rádio.
A escolha correta evita desperdício de caracteres e garante compatibilidade com seus editores de áudio favoritos.
Modelo: tts-1 e tts-1-hd
O campo model aceita apenas tts-1 ou tts-1-hd. Ambos utilizam o mesmo motor de síntese e possuem exatamente o mesmo preço por caractere. A diferença reside exclusivamente na qualidade de processamento de áudio.
Use tts-1 para projetos que priorizam velocidade e custo, ou tts-1-hd quando a fidelidade do som for crítica para sua produção final.
Vozes disponíveis
O parâmetro voice exige um dos 8 presets disponíveis. Cada voz possui uma característica distinta, permitindo que você escolha a que melhor se adapta ao tom do seu conteúdo, desde narrativas suutas até promoções energéticas.
Lembre-se que qualquer voz pode falar em qualquer um dos 23 idiomas suportados. Se o texto for em latim mas não for inglês, defina o campo language explicitamente para evitar suposições incorretas.
- aria, nova, luna, sage (femininas)
- felix, milo, atlas, orion (masculinas)
Formato de resposta
O campo response_format determina o tipo de arquivo de áudio retornado. Você pode escolher entre mp3, wav, opus, flac ou pcm. O mp3 é o padrão mais comum para web, enquanto o wav oferece qualidade sem perda.
O formato pcm é útil para processamento bruto, e o opus oferece compressão eficiente com boa qualidade. A escolha depende da compatibilidade do seu software de edição ou plataforma de distribuição.
Limites e taxa de requisição
Para manter a estabilidade do serviço durante seus picos de criação de conteúdo, a API impõe um limite de 60 requisições por minuto por chave. Antes da primeira recarga, esse limite é mais restrito: apenas 10 requisições por minuto.
O processamento ocorre em fila sequencial, o que significa que textos longos ou alta demanda podem gerar tempos de espera variáveis. Monitorar esses limites ajuda a evitar interrupções no fluxo de produção dos seus áudios.
60 requisições por minuto
O padrão do serviço permite até 60 requisições por minuto. Para contas novas sem recarga, o limite inicial é de 10 requisições por minuto, garantindo uso equilibrado.
- Limite padrão: 60 req/min.
- Limite inicial sem recarga: 10 req/min.
- Contagem por chave de API.
Limite de caracteres
Cada requisição pode processar até 4.096 caracteres. Textos que excedam esse valor devem ser divididos manualmente para garantir a entrega completa do áudio.
- Máximo de 4.096 caracteres por POST.
- Espaços e pontuação contam como caracteres.
Tratamento de erros
Se a síntese falhar, o valor é devolvido integralmente. Monitore os códigos de status HTTP para ajustar sua integração e evitar cobranças indevidas em falhas do servidor.
- Erros de síntese geram reembolso total.
- Verifique o status HTTP para debugging.

Tratamento de erros comuns
Erros acontecem, mas são fáceis de resolver. Confira os códigos de status para identificar rapidamente problemas de autenticação, limites ou formatos inválidos e manter seu fluxo de criação sem interrupções.
Simples, direto e sem surpresas. Verifique suas credenciais e o tamanho do texto antes de enviar.
Erro de autenticação
Se o cabeçalho Authorization: Bearer tts-... estiver incorreto ou expirado, a API retorna 401. Renove sua chave em /get-api-key/ para invalidar a anterior imediatamente e retome as gerações.
Limite de caracteres excedido
Cada requisição aceita até 4.096 caracteres. Texto maior resulta em erro 413. Divida o roteiro em partes menores e junte os arquivos de áudio resultantes para manter a qualidade.
Formato de voz inválido
Use apenas as 8 vozes pré-definidas (aria, nova, luna, sage, felix, milo, atlas, orion). Qualquer string desconhecida no campo voice gera um erro 400, impedindo a síntese.
Exemplos de vozes e idiomas
Escolher a voz certa é o primeiro passo para dar vida ao seu conteúdo. Nossa API oferece oito vozes distintas, cada uma com uma personalidade única, permitindo que você adapte o tom exato para seus vídeos, spots de rádio ou podcasts, desde narrativas calmas até anúncios energéticos.
Lista de vozes femininas
As vozes femininas cobrem desde narrativas claras até histórias suaves. Aria é ideal para narrações claras e quentes. Nova oferece um tom brilhante e animado, perfeito para promoções. Luna traz suavidade para storytelling, enquanto Sage é a escolha calma e instrucional.
- Aria: narradora clara e quente
- Nova: tom brilhante e animado
- Luna: suave, ideal para storytelling
- Sage: calma e instrucional
Lista de vozes masculinas
As vozes masculinas são projetadas para transmitir confiança e proximidade. Felix é energético e ótimo para promoções. Milo soa amigável e conversacional. Atlas mantém neutralidade para notícias, e Orion adiciona profundidade para documentários.
- Felix: energético, ideal para promoções
- Milo: amigável e conversacional
- Atlas: neutro, focado em notícias
- Orion: profundo, ideal para documentários
Suporte a 23 idiomas
Suportamos 23 idiomas, incluindo Árabe, Chinês, Dinamarquês, Holandês, Inglês, Finlandês, Francês, Grego, Hebraico, Hindi, Italiano, Japonês, Coreano, Malaio, Norueguês, Polonês, Português, Russo, Espanhol, Swahili, Sueco e Turco. Qualquer voz pode falar qualquer um destes idiomas. Se não definir o idioma, o sistema tenta adivinhar pelo script; para textos latinos fora do inglês, defina o campo language explicitamente.
Dicas para textos longos
Para narrar roteiros extensos, divida o texto em partes de até 4096 caracteres e envie requisições sequenciais. Cada solicitação gera um arquivo de áudio independente, mantendo a consistência do modelo escolhido.
Divisão em partes de 4096 caracteres
O limite de 4096 caracteres por requisição exige que textos longos sejam segmentados. Garanta que cada parte seja uma unidade semântica coerente para evitar cortes abruptos na fala.
Juntar arquivos de áudio
Após receber os arquivos de áudio individuais, utilize ferramentas de edição ou scripts para concatená-los em um único arquivo final. Isso mantém a continuidade da narração para seus vídeos ou spots.
Gerenciamento de filas
Sob carga, as requisições são processadas uma após a outra, podendo esperar na fila. Para textos longos, planeje o envio considerando que o tempo total inclui essa espera sequencial.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Sua voz adiciona peso e seriedade ao conteúdo, criando uma atmosfera imersiva.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- OpenAI API reference: create speech
- ISO 639 language codes
- Creative Commons Attribution 4.0
- TRON developer hub: TRC-20
- FFmpeg documentation
- LibriTTS-R corpus (OpenSLR 141)
- LibriVox public-domain audiobooks
- LibriTTS-R paper (arXiv 2305.18802)
- IETF RFC 7845: Ogg Opus
- openai-node on GitHub
- Python documentation
