Documentação Completa da API de Síntese de Voz

Por Equ editorial VozBlog · Atualizado 2026-11-18

Esta página documenta os endpoints da API VozBlog, focada em publishers e desenvolvedores WordPress. Aqui você encontra os detalhes técnicos para integrar a síntese de voz aos seus artigos, desde a autenticação até o processamento de requisições JSON.

O guia explica o uso dos parâmetros de modelo, voz e idioma, além de exemplos práticos com cURL e o SDK OpenAI. Você aprenderá a lidar com limites de taxa, formatos de áudio e tratamento de erros, garantindo uma integração robusta e direta ao ponto.

Documentação Completa da API de Síntese de Voz

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

Python (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
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 e Chave API

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

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

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

Ilustração de onda sonora para: 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-hd
  • input: texto até 4096 caracteres
  • voice: voz padrão selecionada
  • speed: 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

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

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

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

Exemplo com cURL

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

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

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

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. FFmpeg documentation
  3. MDN: Web Speech API
  4. openai-node on GitHub
  5. TRON developer hub: TRC-20
  6. Python documentation
  7. Tether (USDT)
  8. IETF RFC 7845: Ogg Opus
  9. Node.js documentation
  10. ISO 639 language codes
  11. OpenAI API reference: create speech
  12. curl documentation

Mais neste site