Documentação da API: Comece a Gerar Áudio Agora

Por Equ editorial NarraTTS Brasil · Atualizado 2026-11-19

Esta documentação é o guia definitivo para criadores de conteúdo e produtores de áudio que precisam integrar narração automatizada aos seus fluxos de trabalho. Aqui você encontra tudo para gerar áudios de alta qualidade via API, desde a obtenção da chave até a execução das primeiras requisições, sem burocracia.

Vamos detalhar os parâmetros essenciais, como escolher entre as 8 vozes disponíveis e ajustar formatos de áudio. Você aprenderá a usar o SDK da OpenAI (ou HTTP direto) com nossa base personalizada, entenderá os limites de taxa e verá exemplos práticos de cURL e Python para começar a criar spots e vídeos hoje mesmo.

Documentação da API: Comece a Gerar Áudio Agora

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

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

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

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

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

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

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

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

Tratamento de erros comuns

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

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

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

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. OpenAI API reference: create speech
  3. ISO 639 language codes
  4. Creative Commons Attribution 4.0
  5. TRON developer hub: TRC-20
  6. FFmpeg documentation
  7. LibriTTS-R corpus (OpenSLR 141)
  8. LibriVox public-domain audiobooks
  9. LibriTTS-R paper (arXiv 2305.18802)
  10. IETF RFC 7845: Ogg Opus
  11. openai-node on GitHub
  12. Python documentation

Mais neste site