Documentação Técnica da API de Síntese de Voz para Livros

Por Equ editorial FábulaVoze · Atualizado 2026-11-19

Esta documentação técnica explica como integrar a API de síntese de voz da FábulaVoze ao seu fluxo de produção de audiolivros e contos infantis. Você encontrará exemplos práticos em cURL e SDKs OpenAI, além de detalhes sobre os 8 vozes licenciadas e os 23 idiomas suportados, ideais para editoras que buscam qualidade sem complexidade.

Explore os parâmetros de entrada, formatos de áudio (MP3, WAV, Opus, FLAC, PCM) e limites de taxa de 60 requisições por minuto. Aqui você aprenderá a gerar arquivos de áudio prontos para distribuição, controlar a velocidade da narração para vozes infantis e gerenciar sua chave de API com segurança e simplicidade.

Documentação Técnica da API de Síntese de Voz para Livros

Perguntas frequentes

Qual o formato de áudio padrão?

O formato padrão é mp3. Você pode especificar outros formatos como wav, opus, flac ou pcm no campo response_format da requisição JSON enviada ao endpoint de síntese. A escolha depende da sua necessidade de compatibilidade com players de audiolivros ou eficiência de armazenamento.

Posso usar o SDK Python?

Sim, utilize o SDK oficial da OpenAI. Basta alterar o base_url para https://api.m799.info/v1 e configurar o cabeçalho de autenticação com sua chave TTS. Isso permite usar as mesmas bibliotecas Python que você já conhece para integrar a síntese ao seu pipeline editorial.

Como alterar a velocidade?

Ajuste o campo speed na requisição JSON. Os valores aceitos variam de 0.25 a 4.0. Um valor de 1.0 representa a velocidade normal. Isso permite adaptar o ritmo da narração para contos infantis ou audiolivros mais densos, mantendo a clareza da voz selecionada.

O que é o modelo tts-1-hd?

É um dos dois modelos disponíveis, ao lado do tts-1. Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço por caractere. A escolha entre eles não impacta o custo nem a velocidade de geração, apenas a configuração do campo model.

Existe suporte para SSML?

Não. A API aceita apenas texto simples no campo input. Não há suporte para marcação SSML, nem para dicionários de fonemas ou pronúncia personalizada. Se precisar de pausas ou ênfase específicas, você deve dividir o texto em partes e ajustar a velocidade manualmente.

Como tratar erros de rate limit?

O limite é de 60 requisições por minuto por chave. Se exceder, implemente lógica de retry com backoff exponential no seu código. Para volumes maiores, considere emitir uma nova chave, pois a anterior será invalidada imediatamente, permitindo reiniciar a contagem de requisições por minuto.

Posso enviar texto em UTF-8?

Sim, o campo input suporta texto UTF-8. Isso permite o uso de acentos, emojis e caracteres especiais comuns em português e outros idiomas suportados. O limite de 4096 caracteres aplica-se ao tamanho do texto enviado em cada requisição individual.

O áudio é armazenado?

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

Qual o tamanho máximo do texto?

O limite é de 4096 caracteres por requisição. Para textos longos, você deve dividir o conteúdo em partes menores, enviar cada parte separadamente e, em seguida, juntar os arquivos de áudio resultantes. Isso garante que cada solicitação seja processada corretamente dentro dos limites da API.

Como obter a lista de vozes?

Faça uma requisição GET para o endpoint /v1/voices. Isso retornará a lista completa das 8 vozes disponíveis, seus idiomas e formatos suportados. Use essa informação para selecionar a voz ideal para seu audiolivro, como Aria para narrativas ou Felix para promoções.

Posso usar áudio em vídeo?

Sim, você pode usar o áudio gerado em vídeos. O arquivo contém uma marca d'água inaudível que identifica o conteúdo como fala sintética. Isso é transparente para o ouvinte final, mas garante a procedência do áudio gerado pela nossa API.

Há limite de caracteres por voz?

Não há limite específico por voz. O limite é de 4096 caracteres por requisição, independentemente da voz selecionada. Você pode usar qualquer uma das 8 vozes disponíveis para qualquer idioma suportado, desde que o texto esteja dentro do limite máximo por chamada.

O idioma é detectado automaticamente?

Sim, o idioma é detectado automaticamente a partir do script do texto. Para textos em latim não ingleses, recomendamos definir o campo language explicitamente. Isso garante a pronúncia correta, especialmente para idiomas como português, espanhol ou japonês, evitando erros de síntese.

Como gerar áudio em WAV?

Defina o campo response_format como wav na sua requisição JSON. O endpoint retornará o arquivo de áudio no formato WAV selecionado. Você pode escolher entre mp3, wav, opus, flac ou pcm, dependendo da qualidade e compatibilidade necessárias para sua plataforma de distribuição.

Primeira solicitação

curl

curl https://api.m799.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.m799.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.m799.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 na API de síntese de voz da FábulaVoze é feita através de um token Bearer incluído no cabeçalho HTTP de cada requisição. Este método garante que apenas editores autorizados possam converter seus textos em áudio, mantendo a integridade dos seus ativos digitais.

Você receberá sua chave única na página de cadastro, onde também poderá visualizar seu saldo e histórico de uso. Utilize o formato Authorization: Bearer sua-chave-aqui para garantir que todas as chamadas à API sejam processadas corretamente.

Token Bearer

Token Bearer

O token é uma string alfanumérica que inicia com tts- e deve ser enviado no cabeçalho Authorization de todas as requisições POST para o endpoint de síntese. Esse padrão é compatível com SDKs modernos e facilita a integração em qualquer ambiente de desenvolvimento.

Chave única por conta

Chave única por conta

Cada conta possui apenas uma chave ativa por vez. Isso simplifica o gerenciamento de acesso para editoras que não necessitam de múltiplos desenvolvedores com permissões distintas simultaneamente, reduzindo a complexidade de controle de acesso.

  • Gere sua chave em /get-api-key/
  • Visualize o saldo e uso em tempo real
  • Formato padrão tts-...

Revocação imediata

Se sua chave for comprometida ou se você desejar renovar seu acesso, a geração de uma nova chave invalida a anterior instantaneamente. Não há período de transição; a chave antiga deixa de funcionar no momento exato da emissão da nova.

Endpoint Principal

Ilustração de onda sonora para: Endpoint Principal

A síntese de áudio ocorre através de uma única chamada HTTP POST para o endpoint principal. Editoras enviam o texto do conto ou capítulo e recebem o arquivo de áudio pronto para distribuição.

O processo é direto: o sistema processa a entrada e retorna o áudio na velocidade típica de cerca de 25 caracteres por segundo. Para textos longos, basta dividir o conteúdo em partes de 4096 caracteres e unir os arquivos resultantes.

A API devolve o arquivo completo, simplificando a integração com os sistemas de publicação digital.

POST /v1/audio/speech

O endpoint aceita requisições POST para https://api.m799.info/v1/audio/speech. É o único ponto de entrada necessário para gerar o áudio a partir do texto fornecido.

A estrutura da requisição segue o padrão do OpenAI, permitindo o uso de SDKs existentes sem adaptações complexas. Basta ajustar a URL base e fornecer a chave de autenticação.

  • Método: POST
  • URL: /v1/audio/speech
  • Formato: JSON

JSON body

O corpo da requisição deve ser um objeto JSON contendo os campos essenciais para a síntese. O campo input recebe o texto do livro ou conto.

Os parâmetros model, voice, response_format e speed configuram a qualidade e a entrega do áudio. O campo language é opcional, mas recomendado para textos em línguas não inglesas com script latino.

  • model: "tts-1" ou "tts-1-hd"
  • input: texto até 4096 caracteres
  • voice: escolha entre 8 vozes
  • response_format: mp3, wav, opus, flac, pcm

Método HTTP padrão

Utilizamos o método HTTP padrão para APIs RESTful, facilitando a integração com bibliotecas de clientes comuns. A autenticação é feita via cabeçalho Authorization: Bearer.

Não são necessários protocolos especiais ou configurações de servidor dedicadas. Qualquer ambiente que suporte requisições HTTP padrão pode consumir a API TSB da FábulaVoze.

Parâmetros de Entrada

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

A API aceita dois modelos de síntese: tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de inteligência artificial e possuem preço idêntico de $10 por 1 milhão de caracteres. A escolha entre eles não altera a qualidade percebida nem o custo, oferecendo consistência total na produção de seus audiolivros e contos infantis.

Modelo tts-1 e tts-1-hd

Utilize o campo model no corpo da requisição JSON. Para editoras que buscam padronização de custos, ambos os modelos oferecem a mesma experiência de áudio, facilitando a previsão de gastos sem necessidade de testes extensivos de qualidade sonora.

Texto input até 4096 chars

Cada requisição pode conter até 4.096 caracteres, incluindo espaços e pontuação. Para obras maiores, divida o texto em partes menores e junte os arquivos de áudio gerados. A geração ocorre em sequência, respeitando a taxa de processamento de aproximadamente 25 caracteres por segundo.

Voz e idioma opcionais

Selecione uma das 8 vozes pré-configuradas ou deixe o sistema adivinhar o idioma pelo script. Para textos em latim fora do inglês, defina o campo language explicitamente. Todas as vozes falam os 23 idiomas suportados, permitindo criar narrativas multilíngues com consistência vocal.

Exemplo de workflow: escolha 'luna' para contos infantis suaves ou 'atlas' para narrações informativas. O idioma é opcional; se não informado, o sistema assume inglês para texto em latim.

  • Vozes: aria, nova, luna, sage, felix, milo, atlas, orion
  • Idiomas: 23 disponíveis, incluindo português e espanhol
  • Detecção automática baseada no script do texto

Formatos de Saída

Ilustração de onda sonora para: Formatos de Saída

A API permite selecionar entre cinco formatos de áudio, garantindo que o arquivo final atenda às necessidades específicas da sua produção editorial. Cada formato é otimizado para diferentes etapas do fluxo de trabalho, desde a distribuição web até a arquivamento em estúdio.

MP3 para streaming

O formato MP3 é a escolha padrão para a maioria das aplicações web e apps móveis. Sua compressão com perdas garante tamanho reduzido, ideal para download rápido em plataformas de audiolivros e streaming, mantendo uma qualidade auditiva agradável para o ouvinte final.

WAV para alta fidelidade

O WAV é a opção recomendada para alta fidelidade e Masterização. Por ser um formato sem compressão, preserva todo o detalhamento da síntese de voz, sendo perfeito para editoras que necessitam de arquivos brutos para edições posteriores ou para garantir a máxima qualidade sonora na distribuição.

Opus, FLAC e PCM

Opus e FLAC oferecem compressão eficiente sem perda de qualidade, economizando espaço de armazenamento. O Opus é excelente para eficiência de banda, enquanto o FLAC mantém a integridade do áudio sem ocupação excessiva. O formato PCM fornece dados de áudio brutos, sem compactação alguma, garantindo fidelidade absoluta.

Controle de Velocidade

Ilustração de onda sonora para: Controle de Velocidade

A velocidade de fala é ajustada pelo parâmetro speed (0,25 a 4,0). O padrão é 1,0, mas editoras podem otimizar o tempo de audição. Textos longos geram áudio em tempo real aproximado (25 caracteres por segundo).

Para audiolivros infantis, vozes como Luna ou Nova podem ser ajustadas para narrar com mais calma. Isso garante clareza na dicção sem perder a naturalidade da história.

Range 0,25 a 4,0

O parâmetro speed aceita valores de 0,25 (lento) a 4,0 (rápido). Use valores baixos para contos educativos e altos para resumos rápidos.

  • Valores fracionários são aceitos (ex: 0,75).

Velocidade padrão

A configuração inicial é 1,0. Esta velocidade simula uma leitura natural, adequada para a maioria dos gêneros literários.

Ajuste para crianças

Para contos infantis, reduza a velocidade para 0,8 ou 0,9. Isso ajuda na compreensão de vocabulário novo. Vozes como Aria e Luna funcionam bem nesse ritmo.

Controle de Velocidade

Exemplo CURL

Ilustração de onda sonora para: Exemplo CURL

Use o comando abaixo para enviar seu texto diretamente para a API. Substitua SUA_CHAVE pela chave fornecida no painel e ajuste a voz conforme o tom da sua narrativa infantil.

O arquivo de áudio gerado é salvo localmente para verificação imediata. Para textos longos, divida o conteúdo em partes de até 4096 caracteres e una os arquivos resultantes.

Comando básico

Execute esta chamada para gerar o áudio. A API retorna o arquivo binário diretamente no corpo da resposta.

```bash curl -X POST "https://api.m799.info/v1/audio/speech" \ -H "Authorization: Bearer SUA_CHAVE" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Era uma vez...", "voice": "aria", "response_format": "mp3"}' ```

  • Modelo: tts-1 ou tts-1-hd
  • Voz: aria (narradora clara)
  • Formato: mp3

Arquivo de saída

Redirecione a saída para um arquivo .mp3 ou .wav. Este arquivo já está pronto para upload nas plataformas de streaming de audiolivros.

O arquivo contém uma marca d'água inaudível que identifica o conteúdo como fala sintetizada, conforme exigido para transparência.

Verificação de status

Verifique o código de status HTTP na resposta. Um 200 OK indica sucesso e entrega do áudio.

Códigos 4xx ou 5xx indicam erro de autenticação ou limite de taxa. Solicitações falhas são reembolsadas integralmente.

SDK OpenAI

Ilustração de onda sonora para: SDK OpenAI

Se você já utiliza o SDK oficial da OpenAI, não precisa aprender uma nova biblioteca. A única mudança necessária é apontar o base_url para o nosso endpoint, mantendo toda a estrutura de classes e métodos que você já conhece.

Mudança de base URL

Basta atualizar a configuração de conexão para https://api.m799.info/v1. Todos os métodos de síntese, como Audio.speech(), permanecem idênticos, garantindo que seu código de produção continue funcionando sem adaptações complexas.

Compatibilidade total

Nossa API segue o mesmo formato de corpo JSON da OpenAI. Isso significa que as classes de cliente e manipulação de erros são compatíveis nativamente, facilitando a integração em editores que já usam essas bibliotecas.

Configuração simples

Instale o pacote padrão e defina a chave de API (tts-...) no cabeçalho de autenticação. Em minutos, você estará gerando audiolivros e contos infantis com a mesma facilidade de um script padrão, sem dependências extras ou SDKs proprietários da FábulaVoze.

  • Apenas ajuste a URL base
  • Mantenha a estrutura de JSON padrão
  • Use a mesma chave de API

Limites e Erros

Ilustração de onda sonora para: Limites e Erros

A API impõe um limite de 60 requisições por minuto por chave, com um limite inicial de 10 requisições por minuto até o primeiro depósito. Isso garante estabilidade durante a geração de capítulos longos.

Erros comuns incluem erros 400 (parâmetros inválidos) e 401 (chave incorreta). Solicitações falhas são totalmente gratuitas, sem cobrança de caracteres.

60 requisições por minuto

O limite padrão é de 60 requisições por minuto por chave de API. Antes do primeiro depósito, o limite é reduzido para 10 requisições por minuto. Isso permite processar vários trechos de livros simultaneamente sem sobrecarga.

  • 60 req/min após depósito
  • 10 req/min em teste
  • Limite por chave ativa

Códigos de erro HTTP

O código 400 indica parâmetros inválidos, como formato de áudio não suportado. O 401 sinaliza que a chave de API está incorreta ou expirada. Erros de servidor (5xx) são raros, mas podem ocorrer durante picos de demanda.

  • 400: Parâmetros inválidos
  • 401: Chave incorreta
  • 5xx: Erro de servidor

Tratamento de fila

Sob alta demanda, as requisições podem entrar em uma fila de processamento sequencial. O tempo de espera varia conforme o volume de áudio gerado. Monitorar o status da resposta ajuda a ajustar a taxa de envio.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Essa característica permite que o texto seja transmitido com autoridade, sem impor uma interpretação emocional específica ao ouvinte.

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. IETF RFC 7845: Ogg Opus
  3. TRON developer hub: TRC-20
  4. LibriVox public-domain audiobooks
  5. Tether (USDT)
  6. FFmpeg documentation
  7. MDN: Web Speech API
  8. OpenAI API reference: create speech
  9. curl documentation
  10. openai-node on GitHub
  11. LibriTTS-R paper (arXiv 2305.18802)
  12. Node.js documentation

Mais neste site