Perguntas frequentes
Como obtenho a chave de API?
Acesse a página /get-api-key/ e registre-se utilizando o Google ou e-mail com senha. O sistema exibe a chave Bearer, o saldo e o histórico de uso. Cada conta possui apenas uma chave ativa por site. Se necessário, você pode emitir uma nova chave a qualquer momento, encerrando imediatamente a anterior.
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 escolha entre 'tts-1' e 'tts-1-hd' não altera o custo por milhão de caracteres, mas sim a qualidade do áudio processado. Ambos aceitam os mesmos parâmetros de voz, velocidade e formato de resposta.
Posso usar o SDK oficial da OpenAI?
Sim. A API segue o mesmo formato de requisição do endpoint de fala da OpenAI. Basta alterar o 'base_url' para 'https://api.playcb44.com/v1' e utilizar a chave da NarradorAPI. Isso permite o uso direto dos SDKs da OpenAI sem modificações complexas no código.
Qual o limite de caracteres por requisição?
Cada requisição aceita até 4096 caracteres no campo 'input'. Para textos maiores, você deve dividir o conteúdo em partes menores e unir os arquivos de áudio resultantes. Caracteres incluem espaços e pontuação. O processamento é sequencial, o que pode causar filas sob alta carga.
O que fazer se a requisição falhar?
Não há custo para requisições falhas. Se a síntese falhar, o valor é devolvido integralmente ao seu saldo. Você pode tentar novamente ou ajustar os parâmetros. O tempo de processamento varia, sendo mais rápido para textos curtos e mais lento para textos longos devido à fila.
Como especificar o idioma no código?
Envie o código ISO do idioma no campo 'language' do corpo JSON. Se não especificado, o sistema tenta adivinhar com base no script. Para textos em latim que não são inglês, defina o idioma explicitamente. Idiomas não suportados incluem vietnamita, indonésio e tailandês.
A API suporta streaming de áudio?
Não. A API retorna o arquivo de áudio completo na resposta após o processamento. Não há suporte para streaming, WebSockets ou áudio parcial em tempo real. O cliente deve aguardar o término da geração para receber o arquivo final no formato escolhido.
Posso emitir uma nova chave enquanto uso a antiga?
Sim. Você pode emitir uma nova chave de API a qualquer momento através da página de conta. A chave antiga é encerrada imediatamente após a emissão da nova. Apenas uma chave ativa é válida por conta, garantindo controle preciso sobre o acesso à API.
Primeira solicitação
curl
curl https://api.playcb44.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.playcb44.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.playcb44.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 |
Autenticação
O acesso à API de texto para fala exige autenticação via cabeçalho HTTP. Cada conta possui uma única chave ativa no formato "tts-..." que deve ser enviada como Bearer Token em todas as requisições.
Uso de Bearer Token
Inclua o cabeçalho Authorization: Bearer tts-<sua-chave> em cada solicitação POST ou GET. A ausência ou invidez da chave resulta em erro 401, impedindo a geração de áudio ou o acesso aos metadados de vozes e modelos.
Geração de nova chave
Você pode emitir uma nova chave de acesso a qualquer momento diretamente no painel da sua conta. Isso é útil para rodízio de credenciais ou revogação de acesso em ambientes de desenvolvimento.
Invalidação imediata
A invalidação é instantânea. Ao gerar uma nova chave, a chave anterior deixa de funcionar imediatamente, sem período de Grace period. Isso garante que requisições usando o token antigo sejam rejeitadas pelo endpoint https://api.playcb44.com/v1.
Endpoints Principais
A API REST de NarradorAPI opera através de três endpoints principais, permitindo a integração direta com ferramentas de produção de conteúdo para YouTube. O endpoint POST é o núcleo da geração de áudio, enquanto os GETs fornecem metadados essenciais para a configuração das requisições.
A arquitetura segue o padrão de APIs modernas, facilitando a automação de workflows de criação de vídeos em larga escala sem necessidade de SDKs proprietários, utilizando o SDK da OpenAI ou HTTP direto.
POST para geração de áudio
O endpoint POST https://api.playcb44.com/v1/audio/speech aceita um corpo JSON contendo o texto, o modelo e a voz desejada. Ele retorna o arquivo de áudio diretamente na resposta, pronto para ser integrado ao vídeo.
O texto pode ter até 4096 caracteres por requisição. Para textos mais longos, o cliente deve dividir o conteúdo e concatenar os arquivos de áudio gerados.
- Endpoint: POST /v1/audio/speech
- Resposta: Arquivo de áudio binário (mp3, wav, opus, flac, pcm)
- Entrada: Texto em JSON
GET para lista de vozes
O endpoint GET https://api.playcb44.com/v1/voices retorna a lista completa das 8 vozes disponíveis, seus idiomas suportados e formatos. Isso permite que o criador de conteúdo verifique as opções antes de iniciar a geração em massa.
Cada voz é baseada em gravações licenciadas e possui características específicas, como narração clara ou estilo documental.
- Retorna: lista de vozes, idiomas e formatos
- URL: GET /v1/voices
GET para modelos disponíveis
O endpoint GET https://api.playcb44.com/v1/models lista os modelos tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de síntese e têm o mesmo preço, diferindo apenas na qualidade de áudio processada.
Esta informação é crucial para garantir que as requisições sejam formuladas corretamente conforme a necessidade de qualidade do projeto.
- Retorna: lista de modelos ativos
- URL: GET /v1/models
Parâmetros de Requisição
Os parâmetros de requisição definem a estrutura exata do payload JSON enviado ao endpoint POST /v1/audio/speech. Cada campo é obrigatório para a síntese correta, garantindo que o motor de TTS processe o texto com as configurações de voz, modelo e formato desejadas.
Modelo tts-1 e tts-1-hd
O campo model aceita apenas "tts-1" ou "tts-1-hd". Ambos utilizam o mesmo motor de síntese e possuem o mesmo preço de $0,01 por 1.000 caracteres. A escolha entre eles não altera o custo, mas sim a qualidade do áudio processado.
- Valores válidos: "tts-1" ou "tts-1-hd"
- Custo idêntico para ambos os valores
Vozes disponíveis
O campo voice requer um dos 8 presets disponíveis. Cada voz possui uma timbre distinto, como "aria" para narrativas claras ou "atlas" para notícias. O idioma é inferido automaticamente ou definido via language, permitindo que qualquer voz fale em qualquer um dos 23 idiomas suportados.
- Femininas: aria, nova, luna, sage
- Masculinas: felix, milo, atlas, orion
Formato de resposta
O campo response_format define o codec do arquivo de áudio retornado. As opções válidas são mp3, wav, opus, flac e pcm. O formato escolhido não afeta a latência nem o custo por caractere, apenas o tamanho final do arquivo e a compatibilidade com o player de destino.
- mp3, wav, opus, flac, pcm
Limites e Taxas
A API impõe um limite de 60 requisições por minuto por chave de API, garantindo estabilidade para integrações em larga escala. Esse limite se aplica a todas as operações de geração de áudio, permitindo que criadores de conteúdo automatizem a produção de vídeos sem interrupções súbitas, desde que respeitem a capacidade do sistema.
O limite de caracteres por requisição é de 4096 caracteres, incluindo espaços e pontuação. Para textos mais longos, é necessário implementar lógica de divisão em partes menores e concatenar os arquivos de áudio resultantes, mantendo o controle preciso sobre a duração e a qualidade do conteúdo final.
60 requisições por minuto
O rate limit é calculado por chave de API ativa. Até a primeira recarga, o limite é de 10 requisições por minuto. Após o primeiro depósito via USDT, o limite sobe para 60 requisições por minuto, permitindo maior throughput para produção de conteúdo regular (antes do depósito é 10/min).
Caso o limite seja excedido, a API retornará um erro HTTP 429 (Too Many Requests). É recomendável implementar lógica de retry com backoff exponencial em integrações automatizadas para lidar com picos de demanda sem falhar abruptamente.
- Limite padrão: 60 requisições/minuto por chave após recarga mínima de $5 (10 requisições/min antes da primeira recarga).
- Limite inicial: 10 requisições/minuto para contas sem recarga.
- Erro HTTP 429 aplicado ao exceder a capacidade do minuto.
Limite de caracteres
Cada requisição POST aceita no máximo 4096 caracteres na campo input. Isso inclui todos os espaços, pontuações e caracteres especiais. O limite é rígido e não permite contorná-lo com compressão de texto.
Para textos extensos, como roteiros completos de vídeos, o cliente deve dividir o texto em segmentos menores, enviar múltiplas requisições e concatenar os arquivos de áudio retornados. Isso garante que cada parte seja processada dentro dos parâmetros aceitos pelo motor de síntese.
- Máximo de 4096 caracteres por requisição.
- Inclui espaços e pontuação na contagem.
- Divisão manual necessária para textos longos.
Fila de processamento
As requisições são processadas sequencialmente quando há múltiplas solicitações simultâneas. Para textos longos, o tempo de geração é aproximadamente igual ao tempo real de áudio (cerca de 25 caracteres por segundo de áudio gerado).
Em momentos de alta demanda, uma requisição pode aguardar na fila antes de ser processada. Isso significa que o tempo de resposta pode variar dependendo da carga do sistema, mas a ordem de processamento é mantida para garantir a integridade dos dados.
- Processamento sequencial sob carga.
- Tempo de geração: ~25 caracteres/segundo de áudio.
- Aguardar na fila é comum em picos de uso.
Exemplo com cURL
A geração de áudio via linha de comando oferece uma validação rápida da integração antes da implementação em produção. O comando abaixo demonstra a estrutura mínima necessária para solicitar a síntese de um texto curto utilizando o endpoint padrão.
Este exemplo utiliza o modelo padrão com formato MP3, adequado para a maioria dos fluxos de trabalho de criação de conteúdo para YouTube. A resposta retorna o arquivo de áudio binário diretamente no corpo da requisição.
Comando básico
Execute a seguinte requisição substituindo SEU_TOKEN pela chave fornecida na sua conta e ajustando o texto de entrada.
```bash curl -X POST "https://api.playcb44.com/v1/audio/speech" \ -H "Authorization: Bearer SEU_TOKEN" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Olá, este é um teste de narração para YouTube.", "voice": "aria", "response_format": "mp3"}' \ -o audio_gerado.mp3 ```
Parâmetros de voz
O parâmetro voice aceita um dos oito presets disponíveis. Para um tom de narrador profissional, utilize aria, atlas ou sage. A linguagem é detectada automaticamente para textos em português, mas pode ser forçada via language se necessário.
A velocidade padrão é 1.0, permitindo ajustes entre 0.25 e 4.0 para adaptar o ritmo da narração ao vídeo final.
Esperando resposta
O arquivo de áudio é retornado imediatamente após o processamento. Para textos longos, o tempo de geração aproxima-se do tempo real (aproximadamente 25 caracteres por segundo).
Se a requisição falhar, nenhum crédito é descontado. O arquivo binário pode ser salvo diretamente ou processado via script.

Integração com SDK OpenAI
O SDK da OpenAI pode ser reutilizado para integrar a NarradorAPI com mínima configuração. Basta alterar o parâmetro base_url para apontar para o endpoint correto, permitindo que as bibliotecas existentes continuem funcionando sem modificações na lógica de envio.
Essa abordagem facilita a migração ou a integração em projetos que já utilizam o ecossistema OpenAI, mantendo a compatibilidade com os métodos padrão de geração de áudio.
Configuração de base_url
Defina a variável de ambiente OPENAI_BASE_URL ou passe-a diretamente no construtor do cliente. O valor deve ser https://api.playcb44.com/v1. Isso redireciona todas as chamadas para a infraestrutura da NarradorAPI, mantendo a estrutura de JSON idêntica ao padrão OpenAI.
OPENAI_BASE_URL=https://api.playcb44.com/v1- Compatível com SDKs Python, Node.js e Go
- Não requer alteração na assinatura do método
audio.speech
Uso da biblioteca oficial
Utilize a classe OpenAI importada do pacote da OpenAI. A autenticação ocorre via Authorization: Bearer, utilizando a chave gerada no painel da sua conta. O SDK gerencia automaticamente a serialização JSON dos parâmetros model, input, voice e response_format.
- Instale via
pip install openai - Autenticação via token
tts-... - Suporte a
tts-1etts-1-hd
Exemplo em Python
O código abaixo demonstra a configuração mínima necessária. O cliente envia o texto e recebe o arquivo de áudio binário diretamente na memória, pronto para ser salvo ou transmitido. Certifique-se de que a chave API está definida no ambiente ou passada explicitamente.
Este método é ideal para scripts de automação que geram narrativas para vídeos do YouTube, permitindo controle preciso de velocidade e formato sem dependências externas complexas.
from openai import OpenAIclient = OpenAI(base_url="https://api.playcb44.com/v1")client.audio.speech.create(...)
Tratamento de Erros
O tratamento de erros segue padrões REST convencionais, permitindo integração automatizada robusta. Você deve verificar o código de status HTTP em cada resposta para determinar se a síntese foi concluída com sucesso ou se ocorreu uma falha específica.
Códigos de status HTTP
Utilizamos códigos padrão HTTP para indicar o estado da requisição. O código 200 indica sucesso, enquanto 401 sinaliza autenticação inválida (chave incorreta ou expirada) e 429 indica que o limite de 60 requisições por minuto foi excedido.
Retorno em caso de falha
Em caso de erro, o corpo da resposta contém um objeto JSON com detalhes do erro, facilitando o diagnóstico. A API não armazena o áudio gerado, portanto, se a requisição falhar após o envio, o áudio não estará disponível para recuperação posterior.
Reembolso automático
Se a síntese falhar, o crédito correspondente é devolvido integralmente à sua conta. Não há cobrança para requisições que não resultam em áudio gerado, garantindo que você pague apenas pelos caracteres processados com sucesso.
Metadados e Dados
Os metadados da requisição, incluindo tempo, caracteres processados e status, são armazenados exclusivamente para fins de faturamento e controle de uso.
O texto de entrada é utilizado estritamente para a geração do arquivo de áudio correspondente.
Armazenamento de requisições
Mantemos um registro mínimo das requisições para garantir a precisão na cobrança. Cada entrada inclui a marcação temporal, o volume de caracteres enviados e o estado final da síntese.
- Tempo de processamento
- Contagem de caracteres
- Status da requisição
Uso de texto para áudio
O conteúdo fornecido no campo input é processado diretamente pelo motor de síntese para criar o arquivo de áudio. Não realizamos análise semântica adicional além do necessário para a geração da voz.
Não uso para treinamento
Seu texto e os áudios gerados não são utilizados para treinar ou aprimorar nossos modelos de IA. O áudio é retornado na resposta e não é armazenado permanentemente em nossos servidores após a entrega.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Transforme sua criatividade em uma narrativa envolvente que conecte profundamente com sua audiência fiel.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- W3C WAI: making audio and video accessible
- Creative Commons Attribution 4.0
- ISO 639 language codes
- LibriTTS-R paper (arXiv 2305.18802)
- OpenAI API reference: create speech
- openai-node on GitHub
- Python documentation
- IETF RFC 7845: Ogg Opus
- TRON developer hub: TRC-20
- LibriTTS-R corpus (OpenSLR 141)
- openai-python on GitHub
