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.mp3Python (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 | |
|---|---|
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 |
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
Registre-se em /get-api-key/. A chave é emitida instantaneamente no painel.
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
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
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
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
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.

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