Perguntas frequentes
Qual é o endpoint da API?
O endpoint principal é POST https://api.getpk7.com/v1/audio/speech. Ele aceita um corpo JSON com o texto e as configurações de áudio. Outros endpoints incluem GET /v1/voices para listar vozes e GET /v1/models. A estrutura da requisição é idêntica à da API de fala da OpenAI, facilitando a integração.
Como autenticar a requisição?
Autentique enviando o cabeçalho Authorization: Bearer tts-... junto com sua chave única. Cada conta possui apenas uma chave ativa por vez. Se você emitir uma nova chave, a anterior é invalidada imediatamente. Utilize a chave gerada na página /get-api-key/ para todas as chamadas à API.
Qual o limite de caracteres por request?
Cada requisição aceita até 4096 caracteres no campo input. Isso inclui espaços e pontuação. Para textos mais longos, divida o conteúdo em partes menores e junte os arquivos de áudio resultantes. O limite é rígido por chamada HTTP, garantindo processamento consistente e previsível para cada lote de texto.
Posso usar o SDK oficial do OpenAI?
Sim, os SDKs oficiais da OpenAI funcionam alterando o base_url para https://api.getpk7.com/v1 e usando sua chave de API. A estrutura do corpo JSON é a mesma. Não oferecemos um SDK proprietário, mas a compatibilidade com o ecossistema OpenAI permite integração rápida sem dependências externas adicionais.
Quais formatos de áudio estão disponíveis?
O campo response_format suporta mp3, wav, opus, flac e pcm. Selecione o formato adequado ao seu fluxo de trabalho. O formato padrão é mp3, mas wav e opus são opções válidas para diferentes necessidades de qualidade e tamanho de arquivo. Todos os formatos são gerados diretamente pelo motor de síntese.
Como funciona a velocidade de áudio?
O parâmetro speed aceita valores entre 0.25 e 4.0. O padrão é 1.0. Textos longos geram áudio em velocidade aproximadamente real (25 caracteres por segundo). Frases curtas levam alguns segundos. As requisições são processadas em fila, então sob carga, pode haver espera antes da geração iniciar.
O que acontece se a requisição falhar?
Se a síntese falhar, não há cobrança. O valor é devolvido integralmente ao seu saldo. Apenas requisições bem-sucedidas consomem créditos. Isso garante que você pague apenas pelo áudio gerado com sucesso. A falha não afeta seu limite de caracteres ou velocidade de processamento para tentativas subsequentes.
Qual o limite de requisições por minuto?
O limite é de 60 requisições por minuto por chave. Antes do primeiro recarga, o limite é de 10 requisições por minuto. Isso se aplica a todas as chamadas simultâneas ou sequenciais. Exceder o limite resulta em erro, aguardando o intervalo para retomar o processamento normal das requisições.
Primeira solicitação
curl
curl https://api.getpk7.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.getpk7.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.getpk7.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 e Chave API
Para consumir a API de síntese de voz, é necessário obter uma chave de API válida no painel da VozBlog. O acesso ao painel ocorre na página /get-api-key/, onde o usuário pode se registrar via Google ou com e-mail e senha. A chave é exibida no painel junto com o saldo e o histórico de uso.
Obtenção da chave no painel
A autenticação é baseada em tokens. Após o registro, o painel exibe a chave ativa, que deve ser copiada para uso nas requisições HTTP.
Header Authorization Bearer
Envie a chave no cabeçalho de cada requisição no formato: Authorization: Bearer tts-.... Essa estrutura é compatível com os SDKs oficiais da OpenAI ao ajustar o base_url.
Revogação imediata de chaves
Uma nova chave pode ser emitida a qualquer momento. A chave anterior é invalidada instantaneamente, garantindo que apenas uma credencial esteja ativa por conta.
Endpoint principal de síntese
O endpoint principal é POST https://api.getpk7.com/v1/audio/speech. Envie um JSON contendo o texto e as configurações de voz para gerar áudio.
A API processa textos de até 4096 caracteres por requisição. Para textos maiores, divida o conteúdo em partes e junte os arquivos resultantes.
Método POST para /v1/audio/speech
Utilize o método HTTP POST para o caminho /v1/audio/speech. O endpoint aceita JSON como corpo da requisição e retorna o arquivo de áudio binário diretamente.
Body JSON com parâmetros
O corpo deve incluir model ("tts-1" ou "tts-1-hd"), input (texto), voice (um dos 8 presets), response_format, speed (0.25–4.0) e language (opcional).
model: tts-1 ou tts-1-hdinput: texto até 4096 caracteresvoice: voz padrão selecionadaspeed: entre 0.25 e 4.0
Resposta com arquivo de áudio binário
A resposta é o arquivo de áudio binário no formato solicitado (mp3, wav, opus, flac ou pcm). Falhas retornam código de erro e estorno do valor.
Parâmetros da requisição
A configuração básica da síntese exige a definição do modelo, do texto de entrada e da voz sintetizadora. O corpo da requisição JSON deve incluir obrigatoriamente o campo model, o texto a ser convertido em input e o identificador da voz em voice.
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, diferenciando-se apenas na qualidade de áudio final.
Input de texto até 4096 caracteres
O texto a ser convertido deve ser inserido no campo input, com limite máximo de 4096 caracteres por requisição. Espaços e pontuação contam como caracteres. Para textos longos, é necessário dividir o conteúdo em partes e unir os arquivos de áudio resultantes.
Voz, idioma e velocidade
O campo voice aceita 8 presets (aria, nova, luna, sage, felix, milo, atlas, orion). O idioma pode ser definido via language (ISO code) ou detectado automaticamente, sendo recomendável a definição explícita para textos em latim não ingleses. A velocidade é ajustável entre 0.25 e 4.0.
- 8 vozes disponíveis com estilos variados
- Detecção automática de idioma ou definição manual
- Velocidade ajustável de 0.25x a 4.0x
Formatos de saída suportados
O parâmetro response_format define a codificação do arquivo de áudio retornado pela API. As opções disponíveis são mp3, wav, opus, flac e pcm, permitindo ajustar a saída conforme a necessidade de largura de banda ou qualidade.
Escolher o formato correto impacta diretamente o tamanho do arquivo e a compatibilidade com o player de áudio do seu blog ou aplicação WordPress.
MP3 para web
O formato MP3 é a escolha padrão para a maioria dos casos de uso na web. Ele oferece uma boa relação entre qualidade e tamanho de arquivo, sendo amplamente suportado por players HTML5 e plugins de WordPress.
Use este formato para garantir a máxima compatibilidade com navegadores modernos e dispositivos móveis sem necessidade de codecs adicionais.
WAV para qualidade máxima
O WAV fornece áudio sem compressão lossy, preservando a fidelidade original da síntese. É ideal para arquivos de áudio que serão editados posteriormente ou arquivados com requisitos de alta qualidade.
O tamanho do arquivo será significativamente maior comparado ao MP3, especialmente para textos longos.
Opus e FLAC para eficiência
O Opus é um codec de áudio moderno que oferece excelente compressão com boa qualidade, ideal para armazenamento em dispositivos com limite de espaço.
O FLAC (Free Lossless Audio Codec) oferece compressão sem perda de dados.
Exemplo com SDK OpenAI
Utilize o SDK oficial da OpenAI para integrar a síntese de voz diretamente ao seu pipeline de desenvolvimento. A configuração exige apenas a alteração da URL base para apontar para a infraestrutura da VozBlog, mantendo toda a compatibilidade com a estrutura de requisições padrão.
O método create processa a conversão de texto em áudio. Após a configuração do ambiente e envio dos parâmetros, o sistema retorna o arquivo de áudio gerado, pronto para ser integrado aos seus posts ou aplicações.
Configuração do base_url
Defina a URL base do cliente para https://api.getpk7.com/v1. Esta configuração permite que o SDK reconheça o endpoint correto da API de síntese, substituindo o domínio padrão da OpenAI sem alterar a lógica de chamada dos métodos.
- Base URL: https://api.getpk7.com/v1
- Autenticação via header Bearer token
- Compatível com SDKs Python e Node.js
Uso do método create
Invoked o método speech.create() passando o modelo (tts-1 ou tts-1-hd), a voz selecionada e o texto de entrada. O SDK serializa os dados em JSON e envia a requisição POST para o endpoint de síntese, aguardando o processamento do servidor.
- Modelos: tts-1, tts-1-hd
- Formatos: mp3, wav, opus, flac, pcm
- Limite: 4096 caracteres por requisição
Recebimento do arquivo
A resposta contém o arquivo de áudio binário diretamente no corpo da resposta HTTP. O SDK retorna o arquivo de áudio, que deve ser escrito em disco ou reproduzido conforme a necessidade da aplicação.

Exemplo com cURL
O uso de cURL oferece uma maneira direta de testar a API sem dependências de bibliotecas externas, ideal para validação rápida em ambientes de desenvolvimento ou scripts automatizados.
Comando básico de POST
Utilize o método POST para o endpoint /v1/audio/speech. O corpo da requisição deve conter JSON com os campos obrigatórios: model, input, voice e response_format. O texto de entrada não pode exceder 4096 caracteres.
Inclusão da chave Bearer
Inclua o cabeçalho Authorization: Bearer sua-chave-aqui para autenticação. Substitua sua-chave-aqui pela chave gerada em /get-api-key/. A ausência ou invidez da chave resultará em erro de autenticação.
Salvamento do arquivo de resposta
Redirecione a saída binária para um arquivo local usando -o. O formato do arquivo dependerá do valor especificado em response_format (mp3, wav, opus, flac ou pcm).
- curl -X POST https://api.getpk7.com/v1/audio/speech
- -H "Authorization: Bearer sua-chave"
- -H "Content-Type: application/json"
- -d '{"model": "tts-1", "input": "Olá mundo", "voice": "nova", "response_format": "mp3"}'
- -o output.mp3
Tratamento de erros
A API retorna códigos de status HTTP padrão para indicar o sucesso ou a falha de cada requisição. Erros de solicitação (4xx) indicam problemas como autenticação inválida ou parâmetros ausentes, enquanto erros do servidor (5xx) sinalizam problemas internos temporários.
O cliente deve verificar o status da resposta para decidir se deve repetir a requisição ou exibir uma mensagem de erro específica ao usuário final.
Códigos de status HTTP
Utilizamos os códigos HTTP padrão para comunicação clara. Um 200 indica que o áudio foi gerado com sucesso. Códigos 400 e 401 indicam erros de parâmetros ou autenticação. Códigos 429 sinalizam limite de taxa excedido. Códigos 500 indicam falhas internas do servidor.
Verifique sempre o cabeçalho da resposta para identificar a natureza exata do erro e agir de acordo.
- 200: Sucesso, áudio retornado
- 400: Erro de sintaxe ou parâmetro inválido
- 401: Chave API inválida ou expirada
- 429: Limite de taxa excedido
- 500: Erro interno do servidor
Reembolso em falhas de síntese
Se a síntese falhar devido a um erro do servidor ou problema de processamento, o valor cobrado é devolvido integralmente. O crédito é restaurado automaticamente na sua conta sem necessidade de solicitação manual.
Isso garante que você não paga por áudio que não foi entregue ou que não pôde ser gerado devido a falhas técnicas.
Limites de taxa excedidos
O limite padrão é de 60 requisições por minuto por chave. Antes do primeiro top-up, o limite é de 10 requisições por minuto. Se você exceder esse limite, receberá um status 429.
Implemente uma lógica de backoff exponencial nas suas aplicações para evitar picos de requisições simultâneas que possam causar bloqueios temporários.
- 60 req/min após top-up
- 10 req/min antes do top-up
- Status 429 quando excedido
Limites e Metadados
A API impõe um limite de 60 requisições por minuto por chave de acesso, garantindo estabilidade. Para novos usuários, o limite inicial é de 10 requisições por minuto até a primeira recarga.
60 requisições por minuto
O limite de taxa é aplicado por chave ativa. Cada conta mantém uma única chave válida; a emissão de uma nova revoga a anterior imediatamente, zerando a contagem de novas requisições.
Metadados de cobrança
O sistema retém metadados de solicitação, incluindo horário, número de caracteres processados e status, exclusivamente para fins de cobrança e auditoria. O texto de entrada não é utilizado para treinamento.
Processamento sequencial
As requisições são processadas em fila única. Embora a síntese seja rápida, sob carga elevada, as solicitações podem aguardar na fila antes da geração do áudio.
Ouça as 8 vozes
Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Em períodos de alta demanda, o tempo de geração aumenta devido à fila de processamento.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
