Documentação técnica da API TTS para integração rápida

Por Equipe editorial AppVoz API · Atualizado 2026-11-18

Esta documentação técnica descreve a integração da API AppVoz para geração de áudio por texto. Aqui você encontra os parâmetros exatos do endpoint, formatos de saída e exemplos de código prontos para uso em projetos mobile.

O guia é direcionado a desenvolvedores e freelancers que buscam uma solução econômica e sem dependência de grandes plataformas. Aprenda a autenticar, listar vozes, lidar com textos longos e gerenciar limites de uso com clareza.

Documentação técnica da API TTS para integração rápida

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.mp3

Python (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
ariafeminino
novafeminino
lunafeminino
sagefeminino
felixmasculino
milomasculino
atlasmasculino
orionmasculino
language
arالعربية
zh中文
daDansk
nlNederlands
enEnglish
fiSuomi
frFrançais
deDeutsch
elΕλληνικά
heעברית
hiहिन्दी
itItaliano
ja日本語
ko한국어
msBahasa Melayu
noNorsk
plPolski
ptPortuguês
ruРусский
esEspañol
swKiswahili
svSvenska
trTürkçe

Autenticação

Ilustração de onda sonora para: 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

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

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

Ilustração de onda sonora para: 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 input aceita 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

Exemplo com curl

Uso com SDK OpenAI

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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

Ilustração de onda sonora para: 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.

Avatar da voz aria
ariafeminino
Avatar da voz nova
novafeminino
Avatar da voz luna
lunafeminino
Avatar da voz sage
sagefeminino
Avatar da voz felix
felixmasculino
Avatar da voz milo
milomasculino
Avatar da voz atlas
atlasmasculino
Avatar da voz orion
orionmasculino

23 idiomas

Qualquer voz fala qualquer um desses idiomas.

Fontes e leituras adicionais

  1. Wikipedia
  2. curl documentation
  3. Python documentation
  4. LibriTTS-R corpus (OpenSLR 141)
  5. MDN: Web Speech API
  6. OpenAI API reference: create speech
  7. LibriTTS-R paper (arXiv 2305.18802)
  8. Node.js documentation
  9. Creative Commons Attribution 4.0
  10. FFmpeg documentation
  11. W3C WAI: making audio and video accessible
  12. IETF RFC 7845: Ogg Opus

Mais neste site