Perguntas frequentes
Qual é o endpoint principal da API?
O endpoint principal é POST https://api.play39w.com/v1/audio/speech. Você envia texto e recebe um arquivo de áudio. O formato da requisição JSON é idêntico ao da API de fala da OpenAI, facilitando a integração imediata.
Posso usar a biblioteca oficial do OpenAI?
Sim. Como o formato da requisição é o mesmo, você pode usar as SDKs oficiais da OpenAI. Basta alterar o base_url para https://api.play39w.com/v1 e utilizar sua chave de API própria para autenticação.
Qual o tamanho máximo do texto por requisição?
Cada requisição aceita até 4096 caracteres. Para textos mais longos, você deve dividi-los em partes menores e juntar os arquivos de áudio gerados. Espaços e pontuação contam como caracteres.
Como defino o idioma da narração?
Você pode definir o idioma usando o campo opcional language com um código ISO. Se não definido, o idioma é adivinhado pelo script; textos em latim assumem inglês por padrão.
O que é o campo 'response_format'?
Este campo define o formato do arquivo de áudio retornado. As opções disponíveis são mp3, wav, opus, flac e pcm. A escolha afeta apenas o formato do arquivo, não a qualidade do motor de 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 escolha entre tts-1 e tts-1-hd não altera custos nem a qualidade base do áudio gerado pela API.
Como funciona o rate limit?
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 erro na requisição.
O que acontece ao exceder os 60 req/min?
A API rejeita as requisições excedentes com erro. Não há fila de espera automática para contornar o limite. Você deve aguardar o reset do contador por minuto ou otimizar suas chamadas.
A API retorna metadados do áudio?
A resposta principal contém o arquivo de áudio. Os metadados de uso, como tempo, caracteres e status, são mantidos para faturamento e podem ser consultados na sua conta, mas não são retornados no corpo da resposta de áudio.
Posso enviar áudio em tempo real?
Não. Não oferecemos streaming, WebSocket ou áudio parcial em tempo real. O áudio é gerado completo e retornado como um arquivo único após o processamento da requisição.
Existe suporte para SSML?
Não. A API aceita apenas texto simples. Não há suporte para marcações SSML, dicionários de fonemas ou controle de pronúncia personalizada além da seleção de voz e velocidade.
Como recuperar uma chave antiga?
A API emite apenas uma chave ativa por conta. Ao gerar uma nova chave, a anterior é invalidada imediatamente. Você não pode recuperar a chave antiga; deve usar a nova ou copiá-la antes da troca.
A resposta é um arquivo ou stream?
A resposta é um arquivo de áudio completo. Não há streaming. O arquivo é gerado internamente e retornado na resposta HTTP após o processamento completo da síntese.
Qual protocolo de autenticação é usado?
Usamos autenticação via Bearer Token. Você deve incluir o cabeçalho Authorization: Bearer tts-... na requisição. Cada conta possui uma chave ativa que pode ser renovada a qualquer momento.
Primeira solicitação
curl
curl https://api.play39w.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.play39w.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.play39w.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: obtenção da chave
Para começar a usar a API de narração por voz da Narador Digital, acesse a página /get-api-key/ e crie sua conta. Você pode se registrar instantaneamente usando o login do Google ou criando um e-mail com senha. Cada conta é vinculada especificamente a este site.
Após o cadastro, o sistema exibe automaticamente sua chave Bearer personalizada. Esta credencial é necessária para autenticar todas as suas requisições de síntese de voz.
Criação de conta no site
Acesse a página de registro e escolha entre login com Google ou e-mail/senha. As contas são independentes por site, garantindo que suas credenciais sejam únicas para esta instância.
- Login rápido via Google
- Registro tradicional com e-mail
- Conta vinculada ao domínio play39w.com
Geração da chave Bearer
Sua chave de API é gerada automaticamente após o cadastro. Ela aparece no painel inicial e deve ser usada no cabeçalho Authorization: Bearer tts-... em todas as chamadas.
- Formato: Bearer tts-...
- Uma chave ativa por conta
- Revoque a chave a qualquer momento
Revisão do saldo e crédito
O painel mostra seu saldo atual e o crédito de teste de $0,50 (válido por 7 dias) se você usou login com Google. Contas criadas com e-mail/senha iniciam sem crédito.
- Saldo visível em tempo real
- Crédito trial de $0,50 (Google)
- Histórico de uso detalhado
Exemplo de solicitação com cURL
Utilize o comando cURL para enviar sua locução diretamente para a API. Substitua SUA_CHAVE pela sua credencial de autenticação e ajuste os parâmetros conforme a necessidade do seu spot publicitário ou vídeo.
O endpoint aceita texto bruto e retorna o arquivo de áudio sintetizado. Este método é ideal para integrações rápidas em pipelines de produção de conteúdo para startups.
Comando básico POST para /v1/audio/speech
Execute a requisição POST para https://api.play39w.com/v1/audio/speech. O cabeçalho deve incluir sua chave Bearer e o tipo de conteúdo JSON.
Inclusão do corpo JSON com texto e voz
Defina o campo input com o texto da locução (máximo 4.096 caracteres). Selecione uma das 8 vozes disponíveis via campo voice e especifique o formato desejado.
Recebimento do arquivo de áudio
A resposta conterá o arquivo de áudio binário. Salve o conteúdo diretamente no formato especificado em response_format para uso imediato em seus comerciais ou vídeos.
Uso com SDK oficial OpenAI
A API Narador Digital segue o formato de requisição do endpoint de fala da OpenAI, permitindo que bibliotecas oficiais sejam utilizadas sem adaptações complexas. Basta ajustar a URL base para apontar para o domínio da API da Narador.
Configuração do base_url personalizado
Para integrar o SDK da OpenAI com a Narador Digital, defina a variável de ambiente ou o parâmetro de configuração base_url como https://api.play39w.com/v1. Isso direciona as chamadas HTTP para nossa infraestrutura de síntese de voz.
Mudança de endpoint na biblioteca
Utilize o mesmo método audio.speech do SDK oficial. A única alteração necessária é a URL base mencionada anteriormente, garantindo que as requisições atinjam o endpoint correto /v1/audio/speech sem modificar a estrutura do código de chamada.
Compatibilidade com código existente
Como o formato do corpo JSON e os parâmetros são idênticos, scripts Python ou Node.js que já consomem a API da OpenAI podem ser migrados facilmente. Apenas atualize a URL base e substitua a chave de autenticação pela chave Bearer da Narador Digital.
Parâmetros de entrada
A API Narador Digital aceita parâmetros padrão que facilitam a integração com seus sistemas de locução. A escolha do modelo e o limite de caracteres são os pontos críticos para garantir a qualidade do áudio gerado para seus comerciais.
Campo 'model' para seleção de qualidade
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 $10 por milhão de caracteres. A distinção está na qualidade de áudio: o tts-1-hd oferece maior fidelidade.
Campo 'input' com limite de 4096 caracteres
Cada requisição aceita até 4.096 caracteres no campo input, incluindo espaços e pontuação. O texto é processado sequencialmente, gerando áudio em tempo real. Para textos maiores, você deve dividir o conteúdo em partes menores e concatenar os arquivos resultantes.
- Máximo de 4.096 caracteres por chamada POST.
- Espaços e pontuação contam como caracteres.
Definição de 'voice' e 'language' opcional
Defina a voice entre as 8 presets disponíveis (ex: nova para upbeat, atlas para neutro). O campo language é opcional: se não fornecido, o sistema adivinha pelo script, assumindo inglês para texto em latim. Para outros idiomas como português ou espanhol, especifique o código ISO para evitar erros.
- 8 vozes disponíveis: aria, nova, luna, sage, felix, milo, atlas, orion.
Formatos de saída disponíveis
O formato de saída é definido pelo campo response_format na requisição JSON. Escolha o formato adequado ao seu pipeline de produção, seja para publicação web, broadcast ou processamento técnico.
MP3 para compactação e web
Ideal para embeds em sites e aplicativos móveis. O arquivo final é leve, garantindo carregamento rápido sem comprometer a inteligibilidade da voz.
Recomendado para comerciais de rádio veiculados via streaming ou plataformas de podcast que exigem otimização de banda.
WAV para alta fidelidade em rádio
Formato sem perda para gravações em estúdio ou masterização. Preserva a qualidade original da síntese para edições posteriores.
Use WAV quando a latência de compressão não for crítica e a integridade do áudio for prioritária para o broadcast.
OPUS, FLAC e PCM para uso específico
OPUS oferece compressão eficiente para transmissão em tempo real. FLAC mantém qualidade lossless com tamanho reduzido. PCM fornece áudio bruto não compactado para processamento imediato.
Selecione estes formatos conforme a necessidade de compatibilidade do seu software de edição ou infraestrutura de transmissão.
- OPUS: baixa latência
- FLAC: lossless compactado
- PCM: áudio bruto

Limites e velocidade
A API limita o volume para garantir estabilidade: cada chave Bearer aceita até 60 requisições por minuto. Para contas novas sem recarga, o limite inicial é de apenas 10 pedidos por minuto.
O processamento é sequencial, sem paralelismo. Isso significa que, sob alta demanda, as solicitações podem aguardar na fila antes de serem executadas.
Limite de 60 requisições por minuto
O limite padrão é de 60 chamadas por minuto por chave. Se você exceder essa quantidade, receberá o código 429 e deverá aguardar até o próximo minuto.
Contas recém-criadas, sem top-up, começam com um limite mais restrito: apenas 10 requisições por minuto. Realize uma recarga mínima para aumentar a capacidade imediata.
- Máximo: 60 requisições/minuto por chave
Velocidade de geração próximo ao tempo real
Para textos longos, a geração de áudio ocorre a uma velocidade aproximada de 25 caracteres de texto por segundo de áudio produzido. Isso significa que um minuto de narração requer cerca de 1.500 caracteres.
Frases curtas podem levar alguns segundos para serem processadas, pois o sistema inicia o motor de síntese para cada solicitação.
Fila de processamento sob carga
Como as requisições são processadas uma após a outra, picos de uso podem fazer com que sua solicitação entre em uma fila de espera.
Isso não afeta a qualidade do áudio ou a contabilidade do saldo, apenas o tempo total até o arquivo estar disponível para download.
Tratamento de erros comuns
Ao integrar a API de narração, erros são esperados. Este guia explica como identificar e corrigir falhas comuns em requisições para o endpoint /v1/audio/speech, garantindo que seu workflow de produção de áudio continue sem interrupções.
Utilize os códigos HTTP retornados para ajustar automaticamente sua aplicação, como retardar tentativas em caso de limite excedido ou validar credenciais antes de enviar textos longos.
Código 401 para chave inválida
Ocorrerá se o token Authorization: Bearer estiver ausente, incorreto ou revogado. Verifique se a chave gerada na página /get-api-key/ está correta e ativa.
Nota: ao emitir uma nova chave, a anterior é invalidada imediatamente.
- Verifique a chave na dashboard.
- Confirme se não há espaços extras.
Código 429 para limite excedido
O limite é de 60 requisições por minuto por chave. Ao atingir este teto, aguarde e tente novamente.
Para startups com alto volume, considere dividir o trabalho ou usar uma única chave estável.
- Limite: 60 req/min.
- Primeiros minutos: 10 req/min.
Mensagens de erro no corpo JSON
Erros de validação, como texto vazio ou formato inválido, retornam detalhes no corpo da resposta JSON.
Leia o campo message para identificar o campo específico que precisa de correção antes de reenviar.
Gestão de texto longo
Para textos excedendo 4.096 caracteres, o fluxo padrão exige dividir o conteúdo em partes menores. Cada fragmento é enviado como uma requisição POST independente ao endpoint de speech, garantindo que o limite do campo input seja respeitado em todas as etapas do processo.
Divisão automática em partes
O texto deve ser segmentado manualmente ou via script antes das chamadas à API. Como cada requisição trata um bloco específico, é responsabilidade do desenvolvedor garantir que a divisão respeite a integridade semântica, evitando cortes abruptos em meio a frases críticas para a narração.
Juntar arquivos de áudio gerados
Após receber os arquivos de áudio individuais (mp3, wav, etc.), é necessário concatená-los na ordem correta. Como a API não realiza o stitch automático, utilize bibliotecas de áudio padrão para unir os blocos em um único arquivo final, pronto para publicação em comerciais ou vídeos.
Consistência de voz entre partes
Para manter a coerência, utilize exatamente o mesmo valor de voice em todas as requisições sequenciais. Como não há estado de contexto entre as chamadas, garantir a uniformidade do timbre depende exclusivamente do envio consistente do parâmetro de voz em cada fragmento processado.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Utilize dados reais de desempenho para escolher a voz que melhor converte para o seu público específico, ajustando o tom conforme necessário.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- openai-python on GitHub
- curl documentation
- Creative Commons Attribution 4.0
- Tether (USDT)
- ISO 639 language codes
- TRON developer hub: TRC-20
- OpenAI API reference: create speech
- LibriTTS-R corpus (OpenSLR 141)
- FFmpeg documentation
- W3C WAI: making audio and video accessible
- LibriVox public-domain audiobooks
