Perguntas frequentes
Como obtenho a chave de API?
Acesse /get-api-key/ para criar sua conta com Google ou e-mail. Após o cadastro, o painel exibe sua chave única (Bearer tts-...) pronta para uso. Você pode emitir uma nova chave a qualquer momento; a anterior é invalidada imediatamente, garantindo segurança total nas suas integrações.
Posso usar o SDK da OpenAI?
Sim. A API segue o mesmo formato de requisição da OpenAI. Basta alterar o base_url para https://api.playbuji.com/v1 e usar sua chave PlayBuji. O SDK oficial da OpenAI funciona nativamente, facilitando a migração e a integração com seus fluxos de trabalho existentes.
Qual o formato recomendado para TikTok?
O formato MP3 é amplamente suportado e eficiente. Você também pode usar WAV, OPUS, FLAC ou PCM via parâmetro response_format. O MP3 oferece boa qualidade com tamanho reduzido, ideal para upload rápido nas plataformas de vídeo curto sem comprometer a fidelidade do áudio gerado.
O que fazer se a requisição falhar?
Se a síntese falhar, o valor é devolvido integralmente ao seu saldo. Não há cobrança para requisições que não geram áudio com sucesso. Verifique os códigos de status HTTP para diagnosticar erros comuns, como limites de caracteres ou problemas de autenticação, e reenvie a solicitação.
Como ajustar a velocidade da voz?
Use o parâmetro speed no corpo da requisição JSON. O valor deve estar entre 0.25 e 4.0. Isso permite acelerar ou desacelerar a narração para se ajustar ao ritmo do vídeo. A velocidade afeta diretamente a duração final do arquivo de áudio gerado.
A API suporta SSML?
Não. A API não suporta marcação SSML, nem dicionários de fonemas ou lexicons personalizados para pronúncia. A entrada é texto simples. Para controlar entonação ou pausas, você deve estruturar o texto manualmente ou dividir em partes menores, já que não há tags de controle de áudio.
Qual o limite de caracteres por pedido?
Cada requisição aceita até 4096 caracteres no campo input. Para textos mais longos, você deve dividir o roteiro em partes desse tamanho e juntar os arquivos de áudio resultantes. Caracteres incluem espaços e pontuação, então planeje a segmentação considerando o volume total de texto do seu script.
Posso gerar áudio em streaming?
Não. A API retorna o arquivo de áudio completo após o processamento. Não há suporte para streaming via WebSocket ou áudio parcial em tempo real. O áudio é gerado e entregue como um arquivo final (mp3, wav, etc.) após a conclusão da síntese no servidor.
A chave expira automaticamente?
Não. Sua chave de API permanece válida até que você decida emiti-la novamente. Ao gerar uma nova chave no painel, a anterior é invalidada instantaneamente. Não há expiração por tempo de inatividade ou data fixa, permitindo que você mantenha suas integrações ativas por tempo indeterminado.
Como vejo meu saldo de caracteres?
Acesse a página /get-api-key/ após fazer login. O painel exibe seu saldo atual, créditos de teste restantes, caracteres consumidos e o histórico de uso. Essas informações permitem que você monitore o consumo e planeje as próximas gerações de áudio.
A API retorna o áudio em base64?
A resposta contém o arquivo de áudio binário diretamente no corpo da resposta HTTP, não em base64. Você deve tratar o payload como um arquivo de áudio padrão. O formato exato depende do parâmetro response_format escolhido (mp3, wav, opus, flac ou pcm) na sua requisição.
Existe versão beta da API?
Não há uma versão beta distinta. A API v1 é a versão estável e única disponível. Os modelos tts-1 e tts-1-hd utilizam o mesmo motor. Os modelos tts-1 e tts-1-hd utilizam o mesmo motor. Todas as atualizações são aplicadas diretamente nesta versão, sem necessidade de migração para ambientes de teste ou versões preliminares separadas.
Posso usar múltiplas chaves?
Não. Cada conta possui apenas uma chave ativa por vez. Você pode gerar uma nova chave a qualquer momento no painel; ao fazer isso, a chave anterior é invalidada imediatamente. Isso garante que apenas uma credencial esteja válida por conta, simplificando a gestão de acesso e segurança.
Qual o timeout máximo de requisição?
O tempo varia conforme a carga. Textos longos geram áudio em tempo real (aprox. 25 caracteres/segundo). Frases curtas levam alguns segundos. Em picos de demanda, as requisições podem aguardar na fila. Não há um timeout fixo documentado, mas a resposta é entregue assim que a síntese completa.
Primeira solicitação
curl
curl https://api.playbuji.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.playbuji.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.playbuji.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 |
Obtenha sua chave de API
Para começar, acesse a página /get-api-key/ do site e crie sua conta. Você pode registrar-se usando o Google ou um endereço de e-mail com senha. Cada conta é vinculada a este site específico e oferece acesso imediato ao painel de controle.
Crie uma conta no site
O registro é simples e leva poucos segundos. Ao utilizar o login com Google, você recebe automaticamente uma tentativa gratuita de $0,50 (aproximadamente 50.000 caracteres), válida por 7 dias. Se preferir e-mail e senha, a conta é criada sem crédito inicial.
Localize a chave no painel
Após o login, o painel exibe sua chave de API ativa, o saldo atual, o uso de caracteres e um exemplo de comando curl pronto para uso. Esta chave é necessária para todas as requisições à API.
Reemita a chave se necessário
Você pode emitir uma nova chave a qualquer momento diretamente pelo painel. Ao gerar uma nova chave, a anterior deixa de funcionar imediatamente, garantindo que você tenha controle total sobre o acesso da sua agência.
Primeira requisição com curl
Para validar sua integração, envie um texto curto via método POST para o endpoint https://api.playbuji.com/v1/audio/speech. O corpo da requisição deve incluir o modelo tts-1, o texto de entrada e o voice desejado. A resposta retornará o arquivo de áudio binário pronto para ser integrado em seus vídeos para TikTok ou Reels.
Exemplo básico de POST
Utilize o comando curl para enviar a requisição. O corpo JSON deve conter os campos model, input e voice. Lembre-se de que o texto não pode exceder 4096 caracteres por solicitação.
- POST https://api.playbuji.com/v1/audio/speech
- Content-Type: application/json
- Body: {"model": "tts-1", "input": "Olá, bem-vindo ao nosso canal", "voice": "nova"}
Inclusão da chave de autenticação
Inclua sua chave API no cabeçalho Authorization. O formato deve ser Bearer tts-sua-chave-aqui. Certifique-se de que a chave corresponde à conta criada na página /get-api-key/.
Parsing da resposta JSON
O servidor retorna o arquivo de áudio diretamente no corpo da resposta. Não há envelope JSON complexo; o conteúdo binário deve ser salvo como o formato escolhido (mp3, wav, opus, flac ou pcm).
Uso com SDK OpenAI
Utilize o SDK oficial da OpenAI ajustando apenas a URL base para https://api.playbuji.com/v1. Isso permite reaproveitar a infraestrutura de clientes já conhecidos, enviando requisições POST para /audio/speech com o formato de corpo JSON padrão.
Ajuste do base_url
Configure o parâmetro base_url do SDK para apontar para o endpoint da PlayBuji. Essa simples alteração redireciona todas as chamadas para nossa infraestrutura de TTS sem exigir mudanças na estrutura do código.
Passagem da chave como Bearer
Inclua sua chave de API no cabeçalho Authorization: Bearer <sua-chave>. O sistema valida automaticamente a permissão e o saldo disponível para processar a síntese de voz solicitada.
Compatibilidade com métodos padrão
Os métodos padrão de geração de áudio funcionam imediatamente. Defina o modelo tts-1 ou tts-1-hd, selecione a voz desejada entre os oito presets e especifique o formato de saída preferido.
- Suporte completo aos parâmetros
input,voice,speederesponse_format. - Compatível com linguagens ISO 639-1 para controle preciso de sotaques.
Formatos de áudio disponíveis
O formato de saída é definido pelo campo response_format na requisição JSON. Você escolhe entre MP3, WAV, OPUS, FLAC ou PCM, dependendo do uso final do áudio gerado pela API.
Cada formato oferece um equilíbrio diferente entre qualidade, tamanho de arquivo e compatibilidade com players e editores utilizados no fluxo de trabalho de produção de vídeos.
MP3 para web e mobile
O MP3 é o padrão para publicação em redes sociais e plataformas de streaming. Ele garante compatibilidade universal com players de vídeo e áudio em dispositivos móveis e navegadores web modernos.
- Alta compatibilidade com TikTok, Reels e Shorts
- Tamanho de arquivo reduzido para carregamento rápido
- Ideal para narração final em vídeos
WAV para alta fidelidade
O formato WAV oferece áudio sem compressão, preservando a fidelidade completa do sinal gerado. É a escolha ideal para edições pós-produção que exigem máxima qualidade de áudio antes da exportação final.
- Áudio sem perda de qualidade
- Ideal para edições em software de desktop
- Maior tamanho de arquivo
OPUS e FLAC para compressão
O OPUS oferece compressão eficiente, enquanto o FLAC garante perda zero de dados. Use OPUS para otimização de banda e FLAC para arquivamento de alta qualidade sem compressão lossy.
- OPUS: compressão eficiente para uso geral
- FLAC: perda zero para arquivamento
- Alternativas leves e de alta qualidade
Tratamento de erros
A API retorna códigos HTTP padronizados para indicar o status de cada síntese. O status 200 indica sucesso, enquanto códigos 4xx ou 5xx sinalham erros de requisição ou falhas no serviço.
As mensagens de erro são descritivas para facilitar a depuração. Importante: se a síntese falhar, o valor é devolvido integralmente, sem custo para você.
Códigos de status HTTP
Receba sempre um código HTTP claro. 200 significa que o áudio foi gerado. 401 ou 403 indicam problemas na chave. 429 significa que o limite de 60 requisições por minuto foi excedido.
Erros 500 são internos e temporários. Retries automáticos simples costumam resolver.
- 200: Sucesso, áudio incluído.
- 401/403: Chave inválida ou expirada.
- 429: Limite de taxa atingido (60 req/min).
- 500: Erro interno temporário.
Mensagens de erro claras
O corpo da resposta contém detalhes sobre o erro, como texto muito longo ou voz inválida. Use essas informações para ajustar os parâmetros da sua próxima chamada.
Requisições falhas são gratuitas
Se a geração do áudio falhar, a cobrança é revertida. Você não paga por tentativas que não resultaram em arquivo final.
Isso garante que apenas o áudio entregue seja facturado, mantendo a transparência nos seus custos de produção.

Limites de taxa e velocidade
O limite padrão é de 60 requisições por minuto por chave. Para agências que processam múltiplos roteiros simultaneamente, esse volume suporta a maioria dos fluxos de produção em escala sem interrupções significativas.
Entender a velocidade de geração e os limites de taxa ajuda a planejar o timing das entregas, especialmente quando há picos de demanda durante campanhas de alto volume.
60 requisições por minuto
Cada chave de API permite até 60 requisições por minuto. Esse limite é suficiente para a maioria das operações de agências que não estão enviando milhares de frases em milissegundos simultâneos.
Limite inicial de 10 requisições
Contas novas começam com um limite reduzido de 10 requisições por minuto. Esse valor aumenta automaticamente para 60 rpm após a primeira recarga de saldo, validando o uso da API.
Aguardamento em fila sob carga
Como as requisições são processadas em sequência, picos de tráfego podem colocar solicitações em uma fila de espera. O tempo de resposta varia conforme a carga do servidor, mas a ordem de chegada é respeitada.
Estrutura da requisição
A estrutura da requisição segue o formato JSON padrão, onde cada campo define como o texto será processado. O corpo da solicitação exige campos obrigatórios para garantir que a síntese de voz seja gerada conforme as necessidades específicas do projeto, desde o conteúdo bruto até as nuances de interpretação.
Cada parâmetro é tratado de forma independente, permitindo combinações precisas. A API não utiliza SSML nem tags de emoção, focando estritamente na configuração direta de texto, voz e velocidade para manter a simplicidade e a previsibilidade da integração técnica.
Campo input para o texto
O campo input aceita a string de texto a ser convertida em áudio. O limite máximo é de 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos mais longos, é necessário dividi-los em partes e juntar os arquivos de áudio resultantes posteriormente.
O idioma é detectado automaticamente pelo script, mas para textos em latim que não sejam inglês, recomenda-se definir o parâmetro language explicitamente para evitar ambiguidades. Caracteres especiais são contados como parte do limite total.
Campo voice para a escolha
O campo voice define o timbre e o estilo da narração. Você pode escolher entre oito presets disponíveis, que variam entre vozes femininas e masculinas. Cada voz possui uma característica específica, como aria para narradoras claras e quentes, ou nova para vozes brilhantes e animadas.
Opções como luna oferecem uma tonalidade suave e narrativa, ideal para histórias, enquanto sage traz calma para instruções. As vozes masculinas incluem felix para promoções energéticas, milo para conversas amigáveis, atlas para notícias neutras e orion para documentários profundos.
- Aria: narradora clara e quente
- Nova: brilhante e animada
- Luna: suave, narrativa
- Sage: calma, instrucional
- Felix: energético e promocional
- Milo: amigável, conversacional
- Atlas: neutro, ideal para notícias
- Orion: profundo, documentário
Campo speed para ajuste
O campo speed permite ajustar a velocidade da fala entre 0.25 e 4.0. O padrão é 1.0, mas ajustes podem ser úteis para sincronizar a narração com vídeos de TikTok ou Reels, onde o ritmo é frequentemente acelerado.
A velocidade afeta diretamente a duração do áudio gerado. Textos longos são processados aproximadamente em tempo real, com cerca de 25 caracteres de texto por segundo de geração, mas requisições curtas podem levar alguns segundos devido ao processamento sequencial.
Autenticação e segurança
A segurança da sua integração depende do cabeçalho Authorization enviado em cada requisição. Sem ele, a API rejeita a solicitação. Este método garante que apenas contas válidas acessem os recursos de síntese.
O formato utiliza um token Bearer que identifica unicamente sua conta. Mantenha essa credencial em variáveis de ambiente para evitar exposição acidental em logs ou código-fonte público.
Uso do cabeçalho Authorization
Inclua o cabeçalho Authorization: Bearer <sua-chave> no cabeçalho de todas as chamadas à API. Isso autentica automaticamente sua agência e deduz o saldo disponível.
- Sempre inclua este cabeçalho em cada request.
Formato Bearer token
O token segue o padrão tts- seguido de caracteres alfanuméricos. Não é necessário codificação extra; passe o valor literal no header.
Uma chave ativa por conta
Cada conta possui apenas uma chave ativa. Se você emitir uma nova, a anterior deixa de funcionar imediatamente. Isso simplifica a gestão de acesso para equipes de agências.
- Issuimento instantâneo.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Verifique sempre a compatibilidade antes de iniciar a produção em massa para evitar retrabalho na locução.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
