Perguntas frequentes
Qual a estrutura do JSON de entrada?
Envie um POST para /v1/audio/speech com model, input (texto), voice, response_format e speed opcional. O campo input aceita até 4096 caracteres. O endpoint aceita o mesmo formato da API de fala da OpenAI, facilitando a integração direta com bibliotecas existentes sem necessidade de adaptações complexas na estrutura dos dados enviados.
Como autenticar a requisição?
Inclua o cabeçalho Authorization: Bearer tts-<sua-chave> em todas as requisições. Sua chave única é gerada ao criar a conta. Se precisar de uma nova chave, pode emiti-la a qualquer momento; a anterior será desativada imediatamente, garantindo que apenas a chave ativa seja utilizada para autenticação nas chamadas da API.
Posso usar o SDK oficial da OpenAI?
Sim, basta alterar a base_url para https://api.playqq1.com/v1 e usar sua chave AppVoz. A estrutura de requisição é idêntica à da OpenAI, permitindo que você utilize as bibliotecas oficiais alterando apenas a URL base. Isso facilita a migração ou o uso simultâneo de diferentes provedores de TTS.
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, pois ambos utilizam o mesmo motor. Você pode usar qualquer um dos dois modelos conforme sua conveniência, mantendo a consistência nos custos por caractere processado na sua conta.
O que é o campo language?
É um código ISO opcional que define o idioma da fala. Se não informado, o sistema tenta adivinhar pelo script do texto (latin defaults to English). Para textos em línguas não inglesas com script latino, defina explicitamente o idioma para garantir a pronúncia correta e evitar erros de interpretação automática.
Como lidar com textos longos?
Divida o texto em partes de até 4096 caracteres. Envie cada parte separadamente e junte os arquivos de áudio resultantes. Como as requisições são processadas em fila, textos muito longos podem levar mais tempo. O tempo médio é de cerca de 25 caracteres por segundo de áudio gerado.
Qual o formato de áudio recomendado?
Escolha entre mp3, wav, opus, flac ou pcm conforme sua necessidade de compatibilidade. O mp3 é leve e amplamente suportado. O opus oferece boa compressão. O formato não altera o preço. Selecione o que melhor se integra ao seu player de áudio ou pipeline de processamento de áudio no aplicativo mobile.
O que significa o status de falha?
Indica que a síntese não foi concluída com sucesso. Solicitações falhas são gratuitas e o valor é devolvido integralmente ao seu saldo. Verifique se o texto está dentro do limite de caracteres ou se a voz selecionada está disponível. Não há custo adicional se o processo de geração interromper antes da conclusão.
Posso alterar a velocidade da voz?
Sim, ajuste o parâmetro speed entre 0.25 e 4.0. Isso permite acelerar ou desacelerar a narração conforme necessário. A velocidade não altera o preço cobrado por caractere. Utilize valores mais baixos para narrativas calmas ou mais altos para anúncios dinâmicos, garantindo que o áudio se adapte ao ritmo do seu app.
Há limite de caracteres por request?
Cada requisição aceita até 4096 caracteres no campo input. Textos maiores devem ser divididos e enviados em múltiplas chamadas. Contam como caracteres espaços e pontuação. Para textos longos, gerencie a divisão para otimizar o tempo de processamento e garantir que o áudio final seja unificado corretamente no lado do cliente.
A API retorna metadados do áudio?
A resposta contém o arquivo de áudio gerado. Metadados como tempo, caracteres e status são mantidos para faturamento, visíveis no painel. O áudio gerado não é armazenado permanentemente após o retorno. Não há metadados extras embutidos no arquivo além da marca d'água inaudível que identifica o áudio como sintetizado.
Posso usar HTTPS?
Sim, a API utiliza HTTPS para todas as comunicações. O endpoint base é https://api.playqq1.com/v1. Isso garante que sua chave e dados sejam transmitidos de forma segura. O uso de HTTPS é padrão e recomendado para todas as integrações, especialmente em apps mobile que podem operar em redes públicas.
Como validar a chave API?
Use sua chave no cabeçalho Authorization. Se estiver válida, a requisição será processada ou rejeitada com erro específico. Você pode ver sua chave ativa e o saldo no painel /get-api-key/. A chave é única por conta e pode ser renovada a qualquer momento, invalidando a anterior instantaneamente.
Onde encontro a lista de vozes?
Acesse o endpoint GET /v1/voices para obter a lista completa de vozes, idiomas e formatos disponíveis. Há 8 vozes predefinidas com descrições específicas. Esta rota também fornece informações sobre os formatos de áudio suportados e preços.
Primeira solicitação
curl
curl https://api.playqq1.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.playqq1.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.playqq1.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
A autenticação na AppVoz API é feita exclusivamente via cabeçalho Bearer. Cada conta possui uma única chave ativa válida para todas as requisições.
Sua chave começa com o prefixo "tts-" e deve ser enviada em cada pedido HTTP para garantir que o uso seja cobrado corretamente.
Chave Bearer
Inclua o cabeçalho Authorization: Bearer tts-... em todas as chamadas. Sem essa informação, a API retorna erro de autenticação.
- Formato: Bearer tts-<sua-chave>
- Visível na página /get-api-key/
Emissão de nova chave
Você pode gerar uma nova chave a qualquer momento diretamente no painel da sua conta.
Isso é útil se sua chave ficar exposta ou se quiser revogar o acesso de um projeto específico.
Invalidação imediata
Ao emitir uma nova chave, a anterior deixa de funcionar instantaneamente.
Não há período de grace period; atualize seu app ou script para usar a nova chave imediatamente.
Endpoint de fala
O endpoint principal para geração de áudio é POST https://api.playqq1.com/v1/audio/speech. Ele aceita texto e retorna o arquivo de áudio sintetizado. A estrutura do corpo da requisição segue o padrão do endpoint de fala da OpenAI, facilitando a integração com bibliotecas existentes.
Para apps mobile, o fluxo é direto: envie o texto e receba o binário. Isso evita complexidade desnecessária e permite que você controle o armazenamento local do áudio gerado conforme a necessidade da sua aplicação.
Método POST
Utilize o método HTTP POST para enviar requisições de síntese. O endpoint está localizado em /v1/audio/speech dentro da base https://api.playqq1.com/v1.
Body JSON padrão
O corpo da requisição deve ser um objeto JSON contendo os parâmetros essenciais. O texto a ser convertido é obrigatório e limitado a 4096 caracteres por chamada.
- O campo
inputaceita strings de texto simples. - A resposta retorna o arquivo de áudio no formato selecionado.
Parâmetros de entrada
Além do texto, você deve especificar o modelo, a voz e o formato de saída. O idioma é opcional; se não definido, o sistema tenta adivinhar com base no script, mas definir explicitamente (ex: 'pt') garante precisão.
model: 'tts-1' ou 'tts-1-hd'.voice: uma das 8 vozes disponíveis.response_format: mp3, wav, opus, flac ou pcm.speed: velocidade entre 0.25 e 4.0.
Vozes e modelos
O endpoint GET /v1/voices lista as 8 vozes disponíveis, com descrições claras de timbre e uso ideal. Você pode filtrar por gênero ou estilo para encontrar a voz que melhor se adapta à narrativa do seu aplicativo.
O endpoint GET /v1/models retorna os modelos suportados, permitindo que você verifique as configurações atuais sem necessidade de adivinhação. A lista é estática e atualizada apenas quando novos motores são adicionados.
Listagem de vozes
Cada voz possui uma identificação única e uma descrição funcional. As vozes femininas incluem Aria (narradora clara), Nova (enerética), Luna (suave) e Sage (instrucional). As masculinas são Felix (promoção), Milo (conversacional), Atlas (neutro) e Orion (documentário).
Todas as vozes suportam os 23 idiomas listados no produto. Se o idioma não for especificado, o sistema tenta adivinhar pelo script do texto, mas é recomendável definir o parâmetro language explicitamente para textos em latim que não sejam inglês.
- Aria: voz feminina, tom narrativo e claro.
- Nova: voz feminina, tom vibrante e otimista.
- Luna: voz feminina, tom suave e contação de histórias.
- Sage: voz feminina, tom calmo e instrucional.
- Felix: voz masculina, tom energético e promocional.
- Milo: voz masculina, tom amigável e conversacional.
Modelos tts-1 e tts-1-hd
A API oferece dois identificadores de modelo: tts-1 e tts-1-hd. Ambos utilizam o mesmo motor de síntese subjacente, garantindo consistência na qualidade vocal entre as duas opções.
O modelo tts-1-hd utiliza o mesmo motor de síntese que o tts-1, garantindo consistência na qualidade vocal entre as duas opções. Para a maioria dos casos de uso mobile, o tts-1 é uma escolha técnica válida.
Mesmo motor e preço
Não há diferença de preço entre os modelos. Ambos são cobrados à taxa padrão de $10 por 1 milhão de caracteres. A escolha entre tts-1 e tts-1-hd é puramente técnica, baseada na preferência de qualidade de áudio.
Como o motor é idêntico, a latência e o processamento são os mesmos. Isso simplifica a integração, pois você não precisa gerenciar custos diferentes para diferentes vozes ou formatos básicos.
Formatos de saída
O formato de saída define como o áudio bruto será entregno na resposta HTTP. Escolha MP3 ou WAV para máxima compatibilidade com players de áudio padrão e frameworks mobile (iOS/Android). Use OPUS ou FLAC para arquivos compactos de alta fidelidade, ideais para reduzir custos de armazenamento e largura de banda em apps.
O formato PCM fornece áudio bruto não compactado. Cada formato tem trade-offs entre tamanho de arquivo e complexidade de decodificação no cliente final.
MP3 e WAV
MP3 é o padrão universal para web e mobile, garantindo reprodução imediata na maioria dos players. WAV oferece qualidade lossless sem compressão, ocupando mais espaço mas sem perda de qualidade.
Ideal para narração de conteúdo onde a compatibilidade é prioritária. O tamanho do arquivo será maior no WAV.
- MP3: compatível universalmente, tamanho moderado.
- WAV: alta fidelidade, arquivo maior.
OPUS e FLAC
OPUS oferece compressão eficiente com boa qualidade, ideal para reduzir custos de transferência em redes móveis. FLAC é lossless, mantendo a qualidade original sem compressão com perda.
Use OPUS para otimizar largura de banda. Use FLAC se precisar de qualidade máxima para edição posterior.
- OPUS: alta compressão, boa qualidade.
- FLAC: lossless, arquivo grande.
PCM bruto
PCM retorna o sinal de áudio bruto, sem cabeçalhos de contêiner. É útil para integrações que processam o áudio bruto.
Requer que o cliente decode o fluxo de bytes para áudio utilizável.
- PCM: sem compressão, sem metadados de contêiner.
Exemplo com curl
Utilize o cURL para testar rapidamente a geração de áudio antes de integrar ao seu aplicativo mobile. O comando abaixo demonstra uma requisição básica para a API.
Comando básico
Execute a requisição POST enviando o texto e a voz desejada. Substitua SUA_CHAVE_AQUI pela sua chave de API ativa.
- curl -X POST https://api.playqq1.com/v1/audio/speech \ -H "Authorization: Bearer SUA_CHAVE_AQUI" \ -H "Content-Type: application/json" \ -d '{"model": "tts-1", "input": "Olá mundo", "voice": "nova", "response_format": "mp3"}'
Cabeçalhos necessários
O cabeçalho Authorization deve conter o prefixo Bearer seguido pela sua chave única. O Content-Type deve ser definido como application/json para garantir o parse correto do corpo da requisição.
Resposta de sucesso
A API retorna o arquivo de áudio binário diretamente no corpo da resposta HTTP 200. Não há wrapper JSON para o áudio, facilitando o armazenamento direto no dispositivo.

Uso com SDK OpenAI
O SDK oficial da OpenAI funciona diretamente com a AppVoz API. Basta alterar o parâmetro base_url para apontar para o nosso endpoint, mantendo o mesmo formato de corpo JSON e o método POST. Isso permite reutilizar bibliotecas já conhecidas.
Alteração do base_url
Configure a URL base para https://api.playqq1.com/v1. Use sua chave API (formato tts-...) no cabeçalho de autenticação. Esta configuração direciona todas as chamadas de síntese para nossa infraestrutura, garantindo compatibilidade imediata com as ferramentas padrão do ecossistema OpenAI.
Compatibilidade de método
O endpoint /audio/speech aceita exatamente o mesmo formato de requisição que o serviço original. Os campos model, input, voice, response_format e speed são idênticos. Você pode migrar suas integrações existentes ajustando apenas a URL base e a chave de autenticação.
Exemplo em Python
Use a biblioteca openai instalada via pip. Defina a URL base e a chave. Execute a criação de áudio passando o texto e a voz desejada. O código retorna o arquivo de áudio pronto para ser reproduzido ou salvo no seu aplicativo mobile.
```python from openai import OpenAI client = OpenAI( base_url="https://api.playqq1.com/v1", api_key="tts-sua-chave-aqui" ) response = client.audio.speech.create( model="tts-1", voice="nova", input="Olá, este é um teste de integração." ) response.stream_to_file("output.mp3") ```
Limites e erros
A API AppVoz impõe limites claros para garantir estabilidade durante a integração em seus apps mobile. Cada chave de API suporta no máximo 60 requisições por minuto para produção. Antes do primeiro recarga, o limite é de apenas 10 requisições por minuto, o que exige cuidado no uso da trial de $0,50.
60 requisições por minuto
O limite padrão de 60 RPM aplica-se por chave ativa. Como as requisições são processadas em fila, textos longos podem ocupar a cota rapidamente. Monitore o uso na página de detalhes da sua chave.
Código 429
Quando o limite é excedido, o servidor retorna o código HTTP 429 Too Many Requests. Isso indica que você deve pausar brevemente antes de enviar mais texto. O tempo de resposta aumenta enquanto a requisição aguarda na fila.
Tratamento de erro
Implemente lógica de retry com backoff exponencial no seu app para lidar com picos de demanda. Se a síntese falhar por erro interno, o valor é devolvido integralmente. Registre os códigos de status para monitorar a saúde da integração em produção.
Tratamento de textos longos
A API aceita no máximo 4096 caracteres por requisição. Para textos maiores, o cliente deve dividir o conteúdo em partes menores antes de enviar.
Split em 4096 caracteres
Divida o texto de entrada em blocos de até 4096 caracteres. Cada bloco deve ser enviado como uma requisição POST independente.
Juntar arquivos de áudio
Receba os arquivos de áudio gerados para cada bloco. Utilize uma biblioteca de áudio para concatenar os arquivos na ordem correta, criando um único arquivo final.
Lógica de cliente
Implemente um loop no seu aplicativo para processar os blocos sequencialmente ou em paralelo, respeitando o limite de 60 requisições por minuto. Aguarde a conclusão de cada parte antes de iniciar a próxima para evitar erros de rate limit.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Acesse a página de criação de conta e escolha entre login com Google ou e-mail.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
Fontes e leituras adicionais
- Wikipedia
- curl documentation
- Python documentation
- LibriTTS-R corpus (OpenSLR 141)
- MDN: Web Speech API
- OpenAI API reference: create speech
- LibriTTS-R paper (arXiv 2305.18802)
- Node.js documentation
- Creative Commons Attribution 4.0
- FFmpeg documentation
- W3C WAI: making audio and video accessible
- IETF RFC 7845: Ogg Opus
