Integração e Uso da API de Texto para Voz

Por equ editorial Vozeis · Atualizado 2026-11-18

Esta documentação explica como integrar a API de síntese de voz da Vozeis em plataformas SaaS voltadas para o setor jurídico. Você aprenderá a enviar textos e receber arquivos de áudio em formatos padrão, garantindo a conformidade técnica para auditoria de contratos e avisos legais.

O guia detalha autenticação, parâmetros de requisição e limites de taxa, com exemplos práticos em cURL e Python. Se você é uma startup buscando custo previsível e integração simples via SDK OpenAI, esta página contém tudo que precisa para começar a emitir áudio sintético em escala.

Integração e Uso da API de Texto para Voz

Perguntas frequentes

Como obter a chave de API?

Acesse a página /get-api-key/ e faça login com Google ou crie uma conta com e-mail e senha. A chave é exibida na interface, iniciada por 'tts-'. Cada conta possui uma chave ativa por site, que pode ser renovada a qualquer momento, invalidando a anterior instantaneamente.

Qual o formato padrão da requisição?

Envie um POST para https://api.aa2259.com/v1/audio/speech com corpo JSON. Inclua os campos obrigatórios: model, input (texto), voice e response_format. O campo speed é opcional. O campo language é opcional. A estrutura segue o padrão do endpoint de fala da OpenAI, facilitando a integração com ferramentas existentes.

A API aceita SSML para marcação?

Não. A API não suporta marcação SSML. Você deve enviar o texto puro no campo 'input'. Se precisar de pausas ou ênfases, utilize a velocidade ou escolha a voz adequada, pois não há suporte para tags de marcação de fala dentro do texto enviado.

Como tratar textos maiores que 4096 caracteres?

Divida o texto em partes de até 4096 caracteres. Envie cada parte em uma requisição separada e, em seguida, junte os arquivos de áudio resultantes. Isso garante que cada solicitação respeite o limite de caracteres definido pela API para o processamento correto da síntese.

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. A diferença está na qualidade do áudio gerado, embora ambos utilizem o mesmo motor e preço. Ambos aceitam os mesmos parâmetros e geram áudio com a mesma qualidade base, permitindo que você escolha qual usar conforme sua preferência de código.

Posso usar o SDK da OpenAI sem modificações?

Sim, mas é necessário ajustar o 'base_url' para https://api.aa2259.com/v1. O formato da requisição é idêntico ao da OpenAI. Você deve substituir a chave de autenticação padrão pela sua chave Vozeis, iniciada por 'tts-', para que as solicitações sejam processadas corretamente.

Como verificar o status da requisição?

O status é determinado pelo código HTTP da resposta e pelo corpo JSON. Se houver erro, a API retorna uma mensagem de erro específica. Pedidos bem-sucedidos retornam o arquivo de áudio ou metadados. A falha na síntese garante o estorno integral da cobrança na sua conta.

A API retorna código de erro em caso de falha?

Sim. Se a síntese falhar, a API retorna um código de erro HTTP apropriado. Além disso, o valor correspondente à falha é devolvido integralmente para o seu saldo. Isso garante que você não seja cobrado por processamentos que não resultaram em áudio gerado com sucesso.

Quais formatos de áudio são suportados?

Você pode solicitar os formatos mp3, wav, opus, flac ou pcm. Especifique o formato desejado no campo 'response_format' da requisição JSON. A escolha depende da sua necessidade de compatibilidade com players ou sistemas de armazenamento, sem custo adicional entre as opções disponíveis.

Existe limite de tamanho de arquivo de áudio?

O limite aplica-se ao texto de entrada, que deve ter até 4096 caracteres por requisição. Não há um limite de tamanho especificado para o arquivo de áudio resultante, mas o tamanho final dependerá da duração e do formato escolhidos. Textos longos devem ser divididos para respeitar o limite de caracteres.

O áudio é gerado instantaneamente?

Não. A geração leva tempo, aproximadamente 25 caracteres por segundo para textos longos. Pedidos curtos podem levar alguns segundos. As solicitações são processadas em fila, então, sob carga, pode haver espera. O tempo varia conforme o tamanho do texto e a velocidade definida.

Posso enviar texto em múltiplos idiomas?

Sim. A API suporta 23 idiomas, incluindo português, inglês, espanhol e japonês, entre outros listados na documentação. Se o idioma não for especificado, ele será adivinhado pelo script (texto latino assume inglês). Para textos em latim que não são inglês, defina o campo 'language' explicitamente para garantir a pronúncia correta.

Como listar todas as vozes disponíveis?

Faça uma solicitação GET para o endpoint /v1/voices. Esta rota retorna a lista completa de vozes, idiomas, formatos suportados e informações de preço. Você pode usar essa informação para integrar dinamicamente a seleção de vozes na sua interface ou aplicação sem precisar consultar a documentação.

A API suporta streaming de áudio?

Não. A API não oferece streaming, WebSocket ou áudio parcial em tempo real. Você deve aguardar o processamento completo da requisição para receber o arquivo de áudio final. O áudio é entregue apenas após a síntese ser concluída, sem transmissão progressiva dos dados.

Primeira solicitação

curl

curl https://api.aa2259.com/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.aa2259.com/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.aa2259.com/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 API Vozeis utiliza autenticação baseada em token Bearer para proteger suas requisições. Cada conta possui uma única chave ativa, enviada no cabeçalho Authorization: Bearer <sua-chave> em cada chamada à API.

Chave Bearer

Chave Bearer

Sua chave de API é o identificador único que autoriza o uso do serviço. Ela deve ser mantida em sigilo no seu servidor de backend e nunca exposta publicamente em código do lado do cliente.

Rotação de chaves

Rotação de chaves

Você pode emitir uma nova chave a qualquer momento diretamente no painel. Ao fazer isso, a chave antiga é invalidada imediatamente, garantindo que acessos indesejados cessem sem atraso.

Segurança da API

Recomenda-se o uso de HTTPS para todas as requisições, já que a chave é enviada no header da HTTP. Como não há suporte por telefone, a gestão segura da chave é sua principal linha de defesa contra uso não autorizado.

O uso em ambientes SaaS para documentos legais se beneficia do controle total sobre quando e como a chave é rotacionada, sem depender de provedores de terceiros para revogação.

  • Envie sempre via HTTPS
  • Armazene a chave no servidor
  • Gere nova chave para invalidar a antiga

Endpoint principal

Ilustração de onda sonora para: Endpoint principal

A rota principal POST /v1/audio/speech converte texto em áudio sintetizado. Envie o texto e as configurações de voz; receba um arquivo de áudio pronto para uso. Ideal para gerar narrações de contratos e avisos legais em plataformas SaaS.

O endpoint aceita requisições JSON padrão, compatível com SDKs OpenAI. O processo é simples: enviar a estrutura com o texto e receber o binário do áudio, facilitando a integração em pipelines automatizados de documentação.

POST /v1/audio/speech

Envie requisições POST para https://api.aa2259.com/v1/audio/speech. Este é o único endpoint necessário para gerar áudio. Não há necessidade de WebSocket ou streaming; o arquivo completo é retornado após o processamento.

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

JSON de entrada

O corpo da requisição deve conter o campo input com o texto (máx. 4096 caracteres). Defina model (tts-1 ou tts-1-hd), voice (ex: aria, atlas) e response_format (mp3, wav, opus, flac, pcm). A velocidade pode ser ajustada entre 0.25 e 4.0.

O campo language é opcional. Se não fornecido, o sistema tenta adivinhar pelo script do texto. Para textos em português com caracteres latinos, defina explicitamente pt-BR para evitar falhas de reconhecimento.

Resposta com áudio

A resposta contém o arquivo de áudio binário no formato solicitado. Se a síntese falhar, o status HTTP indicará o erro e a cobrança é devolvida integralmente. O arquivo gerado é retornado na resposta da API.

Parâmetros de requisição

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

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. A escolha entre eles é baseada apenas na qualidade de áudio desejada, pois ambos têm o mesmo preço.

Modelos tts-1 e tts-1-hd

Os modelos compartilham a mesma infraestrutura de geração. Você pode alternar entre eles conforme a necessidade de fidelidade sonora, mantendo a previsibilidade de custos em $0,01 por 1.000 caracteres processados.

Voizes disponíveis

O campo voice recebe um dos 8 presets fixos. Para documentos legais, recomenda-se vozes neutras ou instrucionais como atlas, sage ou aria, que garantem clareza na leitura de termos contratuais.

  • Female: aria, nova, luna, sage
  • Male: felix, milo, atlas, orion

Formatos de saída

Defina o áudio via response_format. As opções disponíveis são mp3, wav, opus, flac e pcm. Para integração rápida em navegadores, mp3 é o padrão; para arquivos legais que exigem alta fidelidade ou processamento posterior, utilize flac ou wav.

  • mp3, wav, opus, flac, pcm

Limites e performance

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

Textos longos devem ser divididos em partes de até 4096 caracteres e os arquivos de áudio unidos. Cada segmento é processado individualmente e unido ao final para gerar o arquivo de áudio completo,

4096 caracteres por pedido

Cada requisição POST aceita no máximo 4096 caracteres, incluindo espaços e pontuação. Para contratos ou relatórios extensos, o cliente deve implementar a lógica de chunking ou utilizar bibliotecas que gerenciem essa divisão antes do envio.

60 requisições por minuto

O limite padrão é de 60 requisições por minuto por chave de API. Contas novas começam com 10 requisições por minuto até a primeira recarga. Exceder esse limite resulta em erro HTTP 429 (Too Many Requests).

Fila de processamento

As requisições são processadas sequencialmente. Em picos de demanda, uma solicitação pode aguardar na fila até que os recursos estejam disponíveis. O tempo médio é de aproximadamente 25 caracteres por segundo de áudio gerado.

Exemplo com cURL

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

O endpoint POST https://api.aa2259.com/v1/audio/speech aceita texto e retorna o arquivo de áudio sintetizado. Para documentos legais, você pode enviar até 4096 caracteres por chamada, garantindo que o áudio seja gerado com vozes naturais e custo previsível.

Comando básico

Use cURL para enviar sua requisição JSON. O exemplo abaixo sintetiza um aviso legal simples usando a voz sage.

Headers necessários

O cabeçalho Authorization deve conter sua chave Bearer (tts-...). O Content-Type deve ser application/json. Certifique-se de incluir a chave correta para evitar falhas na síntese.

  • Authorization: Bearer sua-chave-aqui
  • Content-Type: application/json

Salvamento do arquivo

Salve a resposta diretamente em um arquivo .mp3 ou .wav usando a flag -o. O áudio gerado é retornado na resposta e não é armazenado.

  • curl -X POST -H "Authorization: Bearer sua-chave" -H "Content-Type: application/json" -d '{"model":"tts-1","input":"Texto do contrato.","voice":"sage"}' -o output.mp3
Exemplo com cURL

Integração com SDK OpenAI

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

A API Vozeis segue o formato de requisição do endpoint de fala da OpenAI. Para integrar, basta alterar o base_url da SDK para https://api.aa2259.com/v1 e utilizar a chave de API da sua conta. Isso permite reutilizar a mesma lógica de chamada já conhecida por muitos desenvolvedores.

Não é necessário instalar um SDK proprietário ou aprender uma nova estrutura de clientes. O padrão JSON mantém a compatibilidade direta, facilitando a migração ou integração em sistemas SaaS que já consomem serviços de TTS similares.

Configuração base_url

Defina a URL base da SDK para apontar para a infraestrutura da Vozeis. Isso redireciona todas as chamadas para o endpoint correto sem alterar a estrutura dos payloads.

A URL base é https://api.aa2259.com/v1. Mantenha a versão v1 para garantir compatibilidade futura com a estrutura de rotas.

  • URL base: https://api.aa2259.com/v1
  • Mantém a estrutura de payload JSON idêntica ao padrão da OpenAI

Uso da mesma classe

Utilize a classe OpenAI ou AzureOpenAI padrão da biblioteca oficial. A única alteração necessária é a URL base e a chave de autenticação (api_key).

O objeto de cliente trata as requisições de geração de áudio exatamente como faria com o serviço original, enviando os parâmetros model, input, voice e response_format.

Exemplo em Python

O código abaixo demonstra a configuração mínima necessária para iniciar a geração de áudio usando o SDK oficial em Python. A chave deve ser passada como string.

Este exemplo é suficiente para integrar a API em scripts de auditoria ou geração de relatórios automáticos em plataformas SaaS.

import os from openai import OpenAI client = OpenAI( base_url="https://api.aa2259.com/v1", api_key=os.getenv("VOZEIS_API_KEY") ) with client.audio.speech.create( model="tts-1", voice="nova", input="Contrato assinado digitalmente com sucesso.", response_format="mp3" ) as response: response.write_to_file("contrato_audio.mp3")

Tratamento de erros

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

A API retorna códigos HTTP padrão para indicar o status da síntese. Erros de solicitação (4xx) indicam parâmetros inválidos, como texto excedendo 4096 caracteres ou formato não suportado. Erros de servidor (5xx) sugerem falhas temporárias na infraestrutura.

Para falhas de autenticação, verifique se o header Authorization: Bearer está correto. Se o texto for muito longo, divida-o manualmente em partes menores antes de enviar.

Códigos HTTP

O serviço utiliza padrões REST claros. Um 200 OK confirma o sucesso. 400 Bad Request indica erro no JSON ou parâmetros fora do esperado. 401 Unauthorized ocorre com chave inválida. 429 Too Many Requests aparece ao exceder 60 requisições por minuto.

Erros internos retornam 500 Internal Server Error. Sob carga, as requisições podem aguardar na fila, processadas sequencialmente.

  • 200: Sucesso, áudio gerado.
  • 400: Parâmetros inválidos ou texto muito longo.
  • 401: Chave API incorreta ou expirada.
  • 429: Limite de 60 req/min excedido.

Mensagens de erro

O corpo da resposta de erro contém uma descrição clara da falha. Isso facilita a depuração rápida em integrações automatizadas. Verifique sempre o campo message para entender se o erro é de formato ou de permissão.

Se o formato de saída não for suportado, o erro indica explicitamente as opções válidas (mp3, wav, opus, flac, pcm).

Retorno de estorno

Requisições falhas são gratuitas. Se a síntese falhar devido a erro do servidor ou problema de conexão, o valor não é debitado ou é estornado integralmente. Não há custo oculto para tentativas falhas.

O saldo da conta reflete apenas as requisições concluídas com sucesso. Monitore o saldo na dashboard para acompanhar o consumo real após falhas.

  • Falhas retornam estorno automático.
  • Não há custo para requisições mal-sucedidas.
  • Saldo atualiza apenas após sucesso.

Voices e idiomas

Ilustração de onda sonora para: Voices e idiomas

A API oferece 8 vozes predefinidas, classificadas por gênero e tom, que podem falar em 23 idiomas distintos. Não há limitação de uso de idioma por voz específica, permitindo flexibilidade na escolha da narrativa para contratos e avisos.

A listagem completa das vozes, idiomas e formatos disponíveis é obtida via GET /v1/voices. Cada arquivo gerado contém uma marca d'água inaudível que identifica o conteúdo como fala sintética.

Listagem via GET /v1/voices

Consulte o endpoint GET /v1/voices para obter a lista atualizada de vozes, idiomas suportados e formatos de áudio disponíveis para sua integração.

Esta rota fornece os dados necessários para configurar corretamente o campo voice nas suas requisições de síntese.

  • Aria (narradora), Nova (dinâmica), Luna (suave), Sage (instrucional)
  • Felix (promo), Milo (conversacional), Atlas (neutro), Orion (documentário)

Definição de idioma

Você pode especificar explicitamente o idioma desejado usando o campo language com um código ISO. Isso garante que a síntese processe o texto na língua correta, evitando ambiguidades.

Utilize esta opção para textos em idiomas que não são o padrão do sistema ou para garantir precisão em documentos multilíngues.

Guessing automático

Se o campo language não for definido, o sistema tenta adivinhar o idioma baseado no script do texto. Para textos em latim fora do inglês, o padrão é inglês.

Defina language explicitamente para textos em latim que não sejam em inglês, garantindo a pronúncia correta para o contexto legal.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. A consistência da resposta é crucial para plataformas SaaS que entregam áudio em tempo de execução.

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

Mais neste site