Documentação técnica da API de síntese de fala

Por Equipe editorial Narrativa Corporativa · Atualizado 2026-11-19

Esta documentação técnica detalha a integração da API de síntese de fala Narrativa Corporativa, projetada para equipes de grandes operações de e-learning e LMS. Aqui, você encontra as especificações técnicas necessárias para gerar trilhas sonoras corporativas em escala, substituindo a dependência de estúdios externos por uma infraestrutura automatizada e previsível.

O guia cobre autenticação, o endpoint principal POST /v1/audio/speech e exemplos práticos com curl e OpenAI SDK. Você aprenderá a configurar parâmetros de voz, velocidade e idioma, além de compreender os limites de 4.096 caracteres por requisição e o tratamento de erros, garantindo a eficiência no processamento massivo de seus cursos.

Documentação técnica da API de síntese de fala

Perguntas frequentes

Como obtenho a chave de API?

Acesse /get-api-key/ e registre-se com Google ou e-mail. O sistema exibe sua chave Bearer (tts-...) e o saldo disponível. É possível emitir uma nova chave a qualquer momento, invalidando a anterior instantaneamente. Cada conta possui apenas uma chave ativa por site.

Qual o formato base da requisição?

Envie um POST para https://api.abc1234.info/v1/audio/speech com corpo JSON. Inclua os campos: model, input (texto), voice, response_format e speed. O texto deve ter no máximo 4096 caracteres. A estrutura é idêntica ao endpoint de fala da OpenAI.

Posso usar o SDK oficial da OpenAI?

Sim. Utilize o SDK oficial da OpenAI ajustando o parâmetro base_url para https://api.abc1234.info/v1. Use sua chave de API Narrativa Corporativa no cabeçalho de autorização. Isso permite integração rápida sem necessidade de bibliotecas proprietárias adicionais.

Qual a diferença entre tts-1 e tts-1-hd?

Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço por caractere. A distinção reside apenas na nomenclatura do modelo enviado na requisição. Não há diferença de custo ou qualidade de áudio entre as duas opções disponíveis na API.

Como definir o idioma manualmente?

Utilize o campo language na requisição com o código ISO correspondente. Se omitido, o sistema tenta adivinhar o idioma, assumindo inglês para texto em latim. Para textos em latim não ingleses, defina o idioma explicitamente para evitar erros de pronúncia.

O que é o parâmetro speed?

Controla a velocidade da fala, aceitando valores entre 0.25 e 4.0. O padrão é 1.0. Valores maiores aceleram a voz, enquanto valores menores a desaceleram. Isso permite ajustar o ritmo do áudio gerado conforme o contexto do curso ou treinamento.

Quais vozes estão disponíveis?

Existem 8 vozes: aria, nova, luna, sage, felix, milo, atlas e orion. Cada uma tem um perfil vocal distinto. Todas as vozes conseguem falar em qualquer um dos 23 idiomas suportados pela API, oferecendo flexibilidade para diferentes estilos de narração.

O áudio é armazenado após a geração?

Não. O arquivo de áudio é retornado diretamente na resposta da requisição e não é armazenado em nossos servidores. Apenas os metadados da solicitação, como tempo, caracteres e status, são mantidos para fins de cobrança e auditoria.

Como faço o tratamento de erros?

Requisições com falha são gratuitas e o valor é devolvido integralmente. Verifique o código de status HTTP na resposta. Para limites de taxa, o sistema retorna erro 429. Implemente lógica de retry exponencial para lidar com filas de processamento sob carga.

Qual o código de erro para limite atingido?

O código HTTP 429 indica que o limite de 60 requisições por minuto foi excedido. Para contas novas, o limite inicial é de 10 requisições por minuto. Aguarde e tente novamente.

Posso enviar texto em UTF-8?

Sim. O campo input aceita strings UTF-8 padrão. Certifique-se de que o texto esteja codificado corretamente antes do envio. Caracteres especiais e acentos são suportados, respeitando os 4096 caracteres máximos por solicitação para garantir a integridade da síntese.

A API retorna metadados do áudio?

A resposta contém o arquivo de áudio binário. Não há metadados adicionais no corpo da resposta. Os metadados de uso são registrados internamente para faturamento e podem ser consultados na conta.

Existe endpoint para listar vozes?

Sim. Utilize GET /v1/voices para obter informações sobre vozes, idiomas e formatos suportados. Este endpoint também exibe o preço atual. É recomendado consultá-lo para validar as opções disponíveis antes de iniciar a integração com a API de síntese.

Posso usar a API em ambiente de produção?

Sim, a API é adequada para produção. Não há garantia de uptime ou SLA oficial. O serviço opera com filas de processamento e limites de taxa. Monitore o status das requisições e implemente lógica de retry para garantir a entrega dos áudios.

Primeira solicitação

curl

curl https://api.abc1234.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.abc1234.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.abc1234.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

Autenticação

Ilustração de onda sonora para: Autenticação

A autenticação é realizada exclusivamente por meio de uma chave Bearer única, válida para cada conta. Essa chave deve ser incluída no cabeçalho de todas as requisições para identificar o usuário e debitar o consumo do saldo disponível.

Cada conta mantém apenas uma chave ativa por vez. A renovação imediata invalida a chave antiga instantaneamente, garantindo controle preciso sobre o acesso da infraestrutura de síntese de fala.

Chave Bearer

Chave Bearer

A chave é gerada e exibida na página /get-api-key/. Ela inicia com o prefixo "tts-" e deve ser protegida como credencial sensível. Não há suporte para múltiplas chaves simultâneas na mesma conta.

  • Prefixo fixo: "tts-"
  • Uma única chave ativa por conta
  • Exibida no painel da conta

Cabeçalho Authorization

Cabeçalho Authorization

O cabeçalho HTTP deve seguir estritamente o formato: "Authorization: Bearer <sua-chave>". Erros de formatação ou chaves inválidas resultam em rejeição imediata da requisição, sem consumo de caracteres.

Renovação de chave

Uma nova chave pode ser emitida a qualquer momento. Ao emitir uma nova chave, a anterior deixa de funcionar imediatamente. Isso permite revogação instantânea em caso de exposição sem necessidade de espera.

Endpoint principal

Ilustração de onda sonora para: Endpoint principal

O endpoint principal POST /v1/audio/speech recebe texto e retorna áudio. O corpo da requisição é JSON. Use tts-1 ou tts-1-hd.

O modelo define a qualidade e o preço. Ambos usam o mesmo motor de síntese. A diferença está na eficiência de processamento.

POST /v1/audio/speech

Envie texto via POST para gerar áudio. A resposta contém o arquivo binário. O endpoint aceita requisições JSON padrão.

O processamento é sequencial. Em alta demanda, as requisições aguardam na fila. Isso garante a ordem de entrega dos arquivos.

  • Método: POST
  • Formato: JSON
  • Resposta: áudio binário

Body JSON

O corpo deve conter model, input, voice e response_format. O campo input aceita até 4096 caracteres. language é opcional.

Campos como speed ajustam a velocidade entre 0.25 e 4.0. A autenticação via Bearer token é obrigatória no cabeçalho.

  • model: "tts-1" ou "tts-1-hd"
  • input: texto (máx. 4096 chars)
  • voice: preset de 8 opções
  • response_format: mp3, wav, opus, flac, pcm
  • speed: 0.25–4.0
  • language: código ISO (opcional)

Modelos tts-1 e tts-1-hd

Os modelos tts-1 e tts-1-hd utilizam o mesmo motor de síntese e têm o mesmo preço. Não há diferença de qualidade percebida nos arquivos gerados.

A escolha entre eles é irrelevante para o custo final. Ambos processam texto e retornam áudio sintetizado. Use o padrão tts-1.

  • Mesmo motor de síntese
  • Mesmo preço ($0.01/1000 chars)
  • Compatibilidade total com SDKs

Exemplo com curl

Ilustração de onda sonora para: Exemplo com curl

O endpoint principal permite a síntese imediata de áudio. Utilize o método POST para enviar o texto e receber o arquivo de voz gerado pela infraestrutura Narrativa Corporativa.

O comando abaixo demonstra uma solicitação direta, substituindo a chave de autenticação e o texto de entrada pelos valores do seu ambiente corporativo.

Comando básico

Execute a seguinte requisição no terminal para gerar o arquivo de áudio. Substitua TTS_API_KEY pela sua chave ativa e ajuste o texto conforme necessário.

  • curl -X POST https://api.abc1234.info/v1/audio/speech
  • -H "Authorization: Bearer TTS_API_KEY"
  • -H "Content-Type: application/json"
  • -d '{"model": "tts-1", "input": "Olá, este é um teste de síntese.", "voice": "nova", "response_format": "mp3"}'

Parâmetros obrigatórios

O corpo da requisição deve conter o campo input com o texto a ser sintetizado, limitado a 4096 caracteres. O modelo tts-1 ou tts-1-hd define a qualidade do áudio.

Defina o voice conforme o preset escolhido e o response_format desejado (mp3, wav, opus, flac ou pcm). O campo language é opcional; se omitido, o idioma será inferido.

Resposta de sucesso

Uma resposta 200 retorna o arquivo de áudio binário diretamente no corpo da resposta. Certifique-se de salvar o output em um arquivo local com a extensão correta.

Não há metadados adicionais no corpo; a estrutura segue o padrão simplificado para integração rápida com sistemas de LMS.

Exemplo com OpenAI SDK

Ilustração de onda sonora para: Exemplo com OpenAI SDK

A API é compatível com o SDK oficial da OpenAI, exigindo apenas a alteração da URL base. Isso permite reutilizar bibliotecas conhecidas sem adaptações complexas no código.

O endpoint utiliza o mesmo formato de corpo JSON, garantindo integração direta com fluxos de trabalho existentes de geração de áudio em larga escala.

Configuração base_url

Defina a variável de ambiente ou passe explicitamente o parâmetro base_url como https://api.abc1234.info/v1. Isso direciona as requisições para a infraestrutura da Narrativa Corporativa em vez da OpenAI.

  • URL base: https://api.abc1234.info/v1
  • Compatível com SDKs Python, Node.js e Go oficiais
  • Necessário apenas ajuste de endpoint, não de lógica

Importação da biblioteca

Instale o pacote oficial via pip: pip install openai. A biblioteca reconhece automaticamente o novo endpoint configurado anteriormente, mantendo a estrutura de chamadas padrão.

Exemplo em Python

O código abaixo demonstra a configuração mínima para gerar áudio. Utilize a chave de API obtida em /get-api-key/ para autenticar as requisições.

```python from openai import OpenAI client = OpenAI( base_url="https://api.abc1234.info/v1", api_key="tts-SEU_CHAVE_AQUI" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Texto para síntese", response_format="mp3" ) response.stream_to_file("output.mp3") ```

Este exemplo envia um texto curto para a voz 'nova'. Para textos longos, lembre-se de dividir o input em blocos de até 4096 caracteres e concatenar os arquivos resultantes.

  • Modelos: 'tts-1' ou 'tts-1-hd'
  • Formatos: mp3, wav, opus, flac, pcm
  • Velocidade ajustável via parâmetro 'speed'

Formatos de áudio

Ilustração de onda sonora para: Formatos de áudio

A API suporta cinco formatos de saída para áudio sintetizado, garantindo compatibilidade com diversos players e sistemas de LMS corporativos. A escolha do formato deve considerar o equilíbrio entre qualidade, tamanho do arquivo e largura de banda disponível para a entrega dos cursos.

MP3

Formato compactado com perda, amplamente suportado por navegadores e players de áudio. Ideal para distribuição web onde o tamanho do arquivo é crítico, mantendo qualidade audível para narração de cursos.

WAV

Áudio não compactado, sem perda de qualidade. Gera arquivos maiores, sendo recomendado para edições internas ou quando a latência de decodificação deve ser mínima em sistemas legados.

OPUS, FLAC, PCM

OPUS oferece alta compressão com qualidade superior. FLAC é lossless (sem perda), útil para arquivamento de alta fidelidade. PCM é áudio bruto, sem compressão, usado para processamento posterior.

  • OPUS: alta eficiência, qualidade superior.
  • FLAC: sem perda de dados.
  • PCM: áudio bruto.
Formatos de áudio

Parâmetros de controle

Ilustração de onda sonora para: Parâmetros de controle

Os parâmetros de controle permitem ajustar a síntese de áudio para atender às necessidades específicas de trilhas sonoras corporativas e e-learning. A seleção da voz e da velocidade influencia diretamente a clareza e o tempo de geração, afetando o custo por caractere em projetos de grande escala.

O campo language é opcional, mas recomendado para textos em línguas latinas distintas do inglês, pois o padrão do sistema é inglês. A definição explícita evita ambiguidades na pronúncia durante a geração massiva de áudios.

Voice (8 presets)

O parâmetro voice aceita oito opções pré-configuradas, cada uma com um perfil vocal distinto. As vozes femininas incluem Aria (narração clara), Nova (dinâmica), Luna (narrativa) e Sage (instrucional). As masculinas oferecem Felix (promoção), Milo (conversacional), Atlas (neutro) e Orion (documentário).

Cada voz é baseada em gravações licenciadas e marca o áudio gerado como sintético. A escolha deve considerar o tom do curso: Sage e Atlas são adequados para instruções técnicas, enquanto Luna e Milo servem para conteúdo mais engajador.

  • Aria: narradora quente e clara
  • Nova: tom luminoso e animado
  • Luna: estilo suave de contação de histórias
  • Sage: calma e instrucional
  • Felix: energético e promocional
  • Milo: amigável e conversacional
  • Atlas: neutro, estilo noticiário
  • Orion: profundo, estilo documentário

Speed (0.25–4.0)

O parâmetro speed aceita valores de 0.25 a 4.0, permitindo ajustar a velocidade de fala. Valores mais altos aceleram a geração, enquanto valores baixos proporcionam uma dicção mais pausada, útil para conteúdos complexos ou não nativos.

O processamento é sequencial, e mudanças na velocidade não alteram o custo por caractere, mas afetam o tempo de resposta. Para grandes volumes, velocidades próximas a 1.0 oferecem o equilíbrio padrão entre eficiência e clareza.

Language (ISO code)

O campo language aceita códigos ISO opcionais para especificar o idioma do texto. Se não fornecido, o sistema tenta adivinhar com base no script, assumindo inglês para textos em caracteres latinos.

Para textos em línguas latinas que não sejam inglês (como francês, italiano ou espanhol), defina explicitamente o código ISO para garantir a pronúncia correta. Idiomas não suportados incluem vietnamita, indonésio, tailandês, ucraniano, romeno, tcheco e bengali.

  • Defina para textos em latim não-inglês
  • Suporte para 23 idiomas específicos
  • Detecção automática por script

Tratamento de erros

Ilustração de onda sonora para: Tratamento de erros

A API retorna códigos HTTP padrão para indicar o estado da operação. O código 200 indica sucesso, enquanto erros de autenticação ou parâmetros inválidos retornam códigos 4xx. A resposta contém um campo de erro descritivo para facilitar o debug.

Para requisições com falha na síntese, o consumo de caracteres é devolvido integralmente. Não há cobrança para requests que não completam o processo de geração de áudio.

Códigos HTTP

O endpoint retorna 200 OK quando o áudio é gerado com sucesso. Erros de validação ou autenticação falham com 400 ou 401.

Não há garantias de SLA ou uptime, portanto, erros temporários de infraestrutura podem ocorrer sem aviso prévio.

  • 200: Sucesso, áudio disponível na resposta.
  • 400: Parâmetros inválidos ou corpo JSON malformado.
  • 401: Chave API inválida ou expirada.
  • 429: Limite de 60 requisições por minuto excedido.

Mensagens de erro

O corpo da resposta de erro contém uma string explicativa detalhando o problema encontrado no request.

Verifique sempre o campo error.message para identificar a causa raiz e ajustar o payload.

Erros de timeout não são comuns, mas podem ocorrer sob alta demanda de fila.

  • message: Descrição clara do erro.
  • code: Código numérico do erro específico.

Requisições falhas são gratuitas

Se a síntese falhar, o crédito correspondente aos caracteres enviados é estornado na conta imediatamente.

Isso garante que sua equipe não pague por áudio que não foi entregue.

A cobrança só ocorre após a geração concluída com sucesso.

Limites da API

Ilustração de onda sonora para: Limites da API

Para garantir a estabilidade do serviço durante o processamento em massa, a API impõe limites técnicos claros que devem ser considerados no design dos fluxos de geração de áudio corporativos.

O respeito a essas restrições evita erros de entrada e garante que o tráfego seja distribuído de forma previsível entre as requisições.

4096 caracteres por request ['Cada chamada à API aceita no máximo 4.096 caracteres no campo input. Esse limite inclui espaços e pontuação.', 'Para textos longos, é necessário dividir o conteúdo em fragmentos menores, enviar cada parte separadamente e, em seguida, juntar os arquivos de áudio resultantes no pipeline de produção.'] []

60 req/min ['O limite padrão é de 60 requisições por minuto por chave de API. Contas novas começam com 10 req/min até o primeiro top-up.', 'Exceder esse limite resulta em erro HTTP 429. Planeje a velocidade de geração com base no volume de caracteres por minuto para evitar gargalos.'] []

Processamento sequencial ['As requisições são processadas uma após a outra. Em momentos de alta carga, uma solicitação pode aguardar na fila.', 'Isso significa que o tempo de resposta varia conforme o volume, sendo mais rápido para frases curtas e mais lento para textos extensos que requerem múltiplas chamadas.'] []

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. É ideal para narrativas de cursos gerais, onde a dicção precisa e a clareza da articulação garantem que o conteúdo seja absorvido sem fadiga auditiva.

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. openai-python on GitHub
  4. MDN: Web Speech API
  5. curl documentation
  6. OpenAI API reference: create speech
  7. LibriTTS-R corpus (OpenSLR 141)
  8. W3C WAI: making audio and video accessible
  9. Tether (USDT)
  10. LibriTTS-R paper (arXiv 2305.18802)
  11. openai-node on GitHub
  12. TRON developer hub: TRC-20

Mais neste site