Documentação técnica da API de texto para fala

Por Equipe editorial LeitorJurídico · Atualizado 2026-11-18

Esta documentação técnica explica como integrar nossa API de texto para voz diretamente nos fluxos de trabalho das equipes de produto de tecnologia jurídica. Você aprenderá a autenticar, enviar requisições e processar contratos ou petições em áudio de forma programática, garantindo precisão e conformidade de dados.

Utilize os exemplos de código e os parâmetros descritos para converter grandes volumes de texto em arquivos de áudio, respeitando os limites de caracteres e as cotas de velocidade. Esta página é focada na implementação prática, sem promessas excessivas, para que sua equipe possa construir sistemas de leitura automatizada confiáveis e escaláveis.

Documentação técnica da API de texto para fala

Perguntas frequentes

Como obtenho uma chave de API?

Acesse a página /get-api-key/ e faça o cadastro usando Google ou e-mail. O sistema gera uma chave única no formato tts-.... Você pode emitir uma nova chave a qualquer momento; a anterior é invalidada imediatamente.

Qual é o método HTTP para enviar texto?

Utilize o método POST no endpoint https://api.playf33.com/v1/audio/speech. O corpo da requisição deve ser JSON, contendo o texto, o modelo, a voz e o formato desejado para a síntese.

Posso usar o SDK oficial da OpenAI?

Sim. Como o formato de requisição é idêntico, basta alterar o base_url para https://api.playf33.com/v1 e utilizar sua chave de API. Isso permite integração rápida sem necessidade de adaptar bibliotecas existentes.

Como especifico o idioma do texto?

Envie o código ISO da linguagem no campo language. Se não especificado, o sistema tenta adivinhar pelo script (texto latino assume inglês). Para textos em outros idiomas com alfabeto latino, defina o idioma explicitamente.

Quais são os formatos de áudio suportados?

O sistema suporta mp3, wav, opus, flac e pcm. Você deve indicar o formato desejado no campo response_format da requisição JSON. Escolha o formato que melhor se integra ao seu pipeline de áudio atual.

Qual o limite de requisições por minuto?

O limite é de 60 requisições por minuto por chave. Antes da primeira recarga, o limite é de 10 requisições por minuto. Exceder o limite resulta em espera ou erro, conforme a configuração de rate limit.

O que acontece se o limite de caracteres for excedido?

Cada requisição aceita até 4096 caracteres. Para textos maiores, você deve dividi-los em partes, enviar cada parte e depois juntar os arquivos de áudio gerados. Isso garante que cada síntese respeite o limite técnico do endpoint.

Como identifico se uma requisição falhou?

Requisições falhas são gratuitas e o valor é devolvido integralmente. Verifique o status HTTP da resposta e o corpo JSON para detalhes do erro. Isso permite tratar falhas programaticamente sem custos incorridos para o cliente.

O que é o endpoint /v1/voices?

Este endpoint GET retorna a lista de vozes disponíveis, idiomas, formatos suportados e preços. Use-o para descobrir os IDs das 8 vozes disponíveis e verificar as configurações técnicas antes de iniciar a integração do seu produto.

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 a necessidade do conteúdo jurídico ou relatório, mantendo a clareza da fala para a equipe de produto.

Qual o modelo padrão de síntese?

Os modelos disponíveis são tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço. A escolha entre eles depende apenas da qualidade de áudio desejada para o seu projeto.

Como funciona a autenticação Bearer?

Envie sua chave no cabeçalho Authorization: Bearer tts-.... Cada conta possui uma chave ativa. Se você emitir uma nova chave, a anterior é desativada imediatamente, garantindo segurança e controle simples sobre o acesso à API.

Há suporte para SSML?

Não. O sistema não suporta marcação SSML, nem dicionários de fonemas ou lexicons personalizados. A entrada é texto puro, com controle básico de velocidade e seleção de voz. Isso simplifica a integração para equipes de produto.

Onde encontro exemplos de código?

A página /get-api-key/ exibe um exemplo de curl pronto para uso. Além disso, a documentação técnica detalha a estrutura JSON necessária. Utilize esses exemplos como base para implementar a integração no seu sistema de leitura automatizada.

Primeira solicitação

curl

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

Primeiros passos

Ilustração de onda sonora para: Primeiros passos

Acesse /get-api-key/ para registrar-se com Google ou e-mail. A chave é emitida e aparece no painel junto com o saldo e o exemplo de curl.

Obter chave API

Obter chave API

Registre-se em /get-api-key/. A chave é emitida instantaneamente no painel.

Autenticação Bearer

Autenticação Bearer

Envie Authorization: Bearer tts-... em cada requisição.

Endpoint principal

Use POST https://api.playf33.com/v1/audio/speech para converter texto em áudio.

Requisição básica

Ilustração de onda sonora para: Requisição básica

O endpoint principal aceita texto e devolve áudio. Use o método POST para enviar requisições JSON. O texto é processado e retornado como arquivo de áudio, sem necessidade de streaming.

Este método é a base para integrações diretas. Ele permite controle preciso sobre os parâmetros de geração, garantindo que o áudio seja criado exatamente como especificado no corpo da requisição.

Método POST

Utilize o método HTTP POST para enviar seus dados de texto. O endpoint está disponível em https://api.playf33.com/v1/audio/speech. Este é o único ponto de entrada para a síntese de áudio.

Corpo JSON

O corpo deve ser um objeto JSON contendo os campos obrigatórios. O texto não pode exceder 4096 caracteres por requisição. Certifique-se de incluir a chave de autenticação no cabeçalho Authorization.

  • model: "tts-1" ou "tts-1-hd"
  • input: texto a ser convertido (máx. 4096 caracteres)
  • voice: um dos 8 presets disponíveis
  • response_format: mp3, wav, opus, flac ou pcm

Exemplo curl

Use o comando curl para testar rapidamente a API. Substitua sua_chave_api pela sua chave real e ajuste o texto conforme necessário. Este exemplo demonstra uma solicitação básica para geração de áudio.

  • curl -X POST https://api.playf33.com/v1/audio/speech \
  • -H "Authorization: Bearer sua_chave_api" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Contrato válido", "voice": "aria", "response_format": "mp3"}'

Usando SDK OpenAI

Ilustração de onda sonora para: Usando SDK OpenAI

O SDK oficial da OpenAI funciona perfeitamente com nossa API, exigindo apenas a alteração da URL base. Isso permite que equipes de produto integrem a síntese de voz diretamente nos fluxos de trabalho existentes de processamento de dados jurídicos sem necessidade de camadas de compatibilidade complexas.

Alterar base_url

Configure a variável base_url para https://api.playf33.com/v1 e utilize sua chave tts-... no cabeçalho de autorização. Esta configuração direciona as chamadas diretamente para nossos endpoints compatíveis, mantendo a estrutura JSON padrão do POST /v1/audio/speech.

  • Base URL: https://api.playf33.com/v1
  • Auth Header: Authorization: Bearer tts-...

Código Python

Abaixo, um exemplo prático utilizando a biblioteca openai para gerar áudio de um contrato curto. O código demonstra a passagem do modelo tts-1-hd e a voz aria, ideal para narrativas claras de documentos legais.

Código JavaScript

Para ambientes web ou servidores Node.js, a mesma lógica se aplica. Ajuste a baseURL nas configurações do cliente e invoque o método audio.speech com os parâmetros de texto e voz desejados, obtendo o arquivo de áudio pronto para reprodução.

Parâmetros de voz

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

Os parâmetros de voz permitem personalizar a saída sonora das suas petições e contratos. Você pode ajustar a entonação e o ritmo para que a leitura soe natural, mantendo a clareza técnica necessária para equipes de produto.

Selecionar voz

Escolha entre oito vozes pré-configuradas, cada uma com timbre específico para diferentes contextos de leitura. Por exemplo, use "atlas" para notícias jurídicas ou "sage" para instruções técnicas.

  • Aria: narradora clara e quente
  • Nova: animada e leve
  • Luna: suave, ideal para histórias
  • Sage: calma e instrucional
  • Felix: energética, para promoções
  • Milo: amigável e conversacional
  • Atlas: neutra, estilo noticiário
  • Orion: profunda, estilo documentário

Velocidade

Ajuste a velocidade de fala entre 0.25x e 4.0x. Isso é útil para adaptar o tempo de geração ou facilitar a escuta de textos densos. O padrão é 1.0x.

Idioma opcional

Especifique o código ISO do idioma para garantir a pronúncia correta. Se não definido, o sistema tenta adivinhar pelo script, assumindo inglês para texto latino. Defina explicitamente para idiomas como português ou espanhol.

Formatos de saída

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

Escolha o formato de saída com base no equilíbrio entre qualidade de áudio, tamanho do arquivo e compatibilidade do seu player. Cada formato atende a diferentes necessidades de integração dentro dos sistemas de leitura automatizada de documentos jurídicos.

MP3

O formato MP3 é a escolha padrão e mais universal, garantindo compatidade imediata com a maioria dos players e dispositivos. Ele oferece uma boa compressão sem perda significativa de clareza para narração de textos longos, como contratos e relatórios.

WAV

O WAV fornece áudio sem compressão, preservando a fidelidade original da voz sintética. Ideal para processamento posterior ou quando a qualidade máxima é prioritária, resultando em arquivos maiores que o MP3.

OPUS e FLAC

O OPUS oferece alta compressão com excelente qualidade, sendo eficiente para transmissão em redes com largura de banda limitada. O FLAC fornece áudio sem compressão (lossless), com tamanho de arquivo menor que o WAV, ideal para arquivamento sem perda de dados.

Formatos de saída

Limites e cotas

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

Para garantir a estabilidade do serviço, cada chave API aceita até 60 requisições por minuto. Até a primeira recarga, o limite inicial é de 10 requisições por minuto. Isso permite testes rápidos sem sobrecarregar o sistema.

Requisições por minuto

O limite padrão de 60 req/min é suficiente para a maioria dos fluxos de processamento em lote. O limite é de 10 req/min antes da primeira recarga e sobe para 60 req/min após a recarga via USDT.

Limite de caracteres

Cada requisição suporta até 4.096 caracteres, incluindo espaços e pontuação. Para textos longos, divida o conteúdo em partes dentro desse limite e junte os arquivos de áudio gerados.

Fila de processamento

As requisições são processadas em sequência. Em momentos de alta demanda, uma solicitação pode aguardar na fila antes da síntese iniciar. Isso garante que a qualidade do áudio permaneça estável, mesmo sob carga.

Tratamento de erros

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

A API retorna códigos HTTP padrão para indicar o status de cada requisição. O código 200 indica sucesso, enquanto 4xx e 5xx sinalizam problemas de autenticação ou servidores. É essencial verificar o status code antes de interpretar o corpo da resposta.

Em caso de falha na síntese, o sistema devolve um JSON de erro detalhado explicando a causa, como texto inválido ou limite excedido. Esses erros não consomem saldo, garantindo que você não pague por áudio que não foi gerado.

Códigos HTTP

O endpoint principal retorna 200 para solicitações bem-sucedidas. Use 401 para chaves inválidas ou expiradas, e 429 para exceder a cota de 60 requisições por minuto.

Erros 5xx indicam problemas temporários no servidor. Em caso de instabilidade, implemente retentativas com backoff exponencial para evitar sobrecarga.

Falha de síntese

Se a geração de áudio falhar, a resposta conterá um código de erro específico e uma mensagem descritiva. O texto enviado permanece intacto para nova tentativa.

Verifique sempre o campo 'error' na resposta JSON para identificar se o problema é de formato ou de limite de caracteres.

Retorno de saldo

Requisições falhas são gratuitas. O valor correspondente à tentativa não bem-sucedida não é debitado da sua conta.

Você pode monitorar o saldo restante e o histórico de uso diretamente no painel da sua conta após o login.

  • 200: Sucesso; áudio disponível no corpo da resposta.
  • 400: Erro de validação nos parâmetros enviados.
  • 401: Chave API inválida ou ausente.
  • 429: Limite de 60 requisições/minuto excedido.
  • 500: Erro interno do servidor.

Endpoints adicionais

Ilustração de onda sonora para: Endpoints adicionais

Além do endpoint principal de geração, a API oferece rotas para inspeção de recursos. Estas permitem que equipes de produto integrem a descoberta de vozes e modelos diretamente nos fluxos de configuração da aplicação, sem necessidade de hardcoding.

Listar vozes

O endpoint GET /v1/voices retorna metadados completos sobre as 8 vozes disponíveis, incluindo idiomas suportados e formatos de saída compatíveis.

  • GET https://api.playf33.com/v1/voices

Listar modelos

Consulte GET /v1/models para verificar os IDs dos modelos de síntese (tts-1 e tts-1-hd) e suas especificações técnicas atuais.

Formatos suportados

Os formatos de áudio disponíveis (mp3, wav, opus, flac, pcm) são listados automaticamente na resposta do endpoint de vozes, facilitando a validação antes da solicitação de síntese.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Oferecemos oito vozes pré-configuradas, selecionadas para atender às demandas específicas de leitura de documentos jurídicos.

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. Tether (USDT)
  4. LibriTTS-R paper (arXiv 2305.18802)
  5. curl documentation
  6. LibriVox public-domain audiobooks
  7. MDN: Web Speech API
  8. IETF RFC 7845: Ogg Opus
  9. OpenAI API reference: create speech
  10. TRON developer hub: TRC-20
  11. ISO 639 language codes
  12. LibriTTS-R corpus (OpenSLR 141)

Mais neste site