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.mp3Python (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 | |
|---|---|
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 |
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
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
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
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
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
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
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.

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
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
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.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
