Documentação técnica da API de texto para fala

Por Equ editorial VoizEngine · Atualizado 2026-11-19

Esta documentação descreve a API de texto para fala do VoizEngine, projetada para criadores de conteúdo e agências que precisam integrar síntese de voz em fluxos de trabalho de produção de vídeos. Utilizamos o formato de requisição compatível com o endpoint de fala da OpenAI, permitindo integração rápida com SDKs existentes sem necessidade de bibliotecas proprietárias ou adaptações complexas.

Aqui você encontrará a especificação técnica completa para geração de áudio via POST /v1/audio/speech, incluindo autenticação, parâmetros obrigatórios como voice e input, e formatos de saída suportados. O guia também cobre limites de taxa (60 req/min), tratamento de erros e exemplos práticos em cURL, garantindo que você possa gerar narrativas consistentes com volume e previsibilidade.

Documentação técnica da API de texto para fala

Perguntas frequentes

Como configuro o base_url no SDK OpenAI?

Defina base_url como https://api.vk444.info/v1. Utilize a chave da API no cabeçalho Authorization: Bearer tts-<sua-chave>. A estrutura do corpo da requisição é idêntica ao endpoint de fala da OpenAI, garantindo compatibilidade direta com os SDKs oficiais sem necessidade de adaptações complexas.

A API suporta streaming de áudio parcial?

Não. A API retorna o arquivo de áudio completo apenas após a síntese terminar. Não há suporte para streaming via WebSocket ou envio de áudio parcial em tempo real. Você deve aguardar o response final para obter o binário do áudio gerado.

Qual o tamanho máximo de texto por requisição?

O limite é de 4096 caracteres por requisição, incluindo espaços e pontuação. Para textos mais longos, você deve dividir o conteúdo em partes menores e juntar os arquivos de áudio resultantes manualmente no lado do cliente para criar a narração completa.

Posso enviar múltiplos textos em uma única chamada?

Não. Cada requisição POST processa apenas um único texto de entrada. Para gerar áudio de múltiplos textos, é necessário realizar chamadas individuais para cada fragmento de texto, respeitando o limite de 4096 caracteres por solicitação.

A API retorna metadados junto com o áudio?

O corpo da resposta contém o arquivo de áudio binário. Metadados de uso, como tempo, caracteres e status, são mantidos para faturamento, mas não são retornados na resposta da API. Consulte o painel de controle para detalhes de consumo.

Como identificar se a requisição falhou ou teve sucesso?

Requisições bem-sucedidas retornam o código HTTP 200 com o arquivo de áudio. Falhas retornam códigos de erro HTTP apropriados. Requisições falhas são gratuitas e o valor é devolvido integralmente. Verifique o status code para determinar o resultado da síntese.

Os formatos opus e flac são recomendados para vídeo?

Sim, são formatos válidos. O opus é eficiente para streaming e o flac oferece perda zero. O mp3 e o wav também são suportados. Escolha o formato que melhor se integra ao seu pipeline de edição de vídeo sem compressão desnecessária.

Existe documentação para WebSockets?

Não. Não há suporte para WebSockets ou streaming. A comunicação é baseada em HTTP REST padrão. Utilize o endpoint POST para enviar texto e receber o arquivo completo. Não há endpoints específicos para conexões persistentes ou bidirecionais.

Como funciona a detecção automática de idioma?

Se o campo language não for definido, o sistema tenta adivinhar pelo script. Texto em latino assume inglês por padrão. Para outros idiomas em latim, defina o código ISO explicitamente para evitar erros de pronúncia na narração do conteúdo.

Posso usar a mesma chave em múltiplos servidores?

Sim. Há uma chave ativa por conta. Você pode utilizá-la em múltiplos servidores ou ambientes simultaneamente. A cota de 60 requisições por minuto aplica-se à chave, não por instância. Uma nova chave revoga a anterior imediatamente.

Qual a latência média de geração de áudio?

Aproximadamente tempo real para textos longos, cerca de 25 caracteres por segundo. Frases curtas levam alguns segundos. Sob carga, as requisições podem entrar em fila e processar-se sequencialmente, aumentando o tempo total de resposta dependendo da fila.

Há versão v2 da API em previsão?

Não há previsão ou anúncio de uma versão v2. A API opera na versão v1 com os endpoints /v1/audio/speech e /v1/voices. Não há cronograma de migração ou novas versões anunciadas para o momento atual.

O SDK OpenAI funciona com node.js e python?

Sim. Como a estrutura JSON é idêntica, os SDKs oficiais da OpenAI funcionam em Node.js e Python. Basta alterar o base_url para https://api.vk444.info/v1 e fornecer sua chave de API no cabeçalho de autenticação adequado.

Como faço o debug de erros de áudio corrompido?

Verifique se o formato de resposta solicitado é suportado. Certifique-se de que o texto está dentro do limite de 4096 caracteres. Se o áudio estiver corrompido, verifique a integridade do arquivo binário recebido e o código de status HTTP da resposta.

Primeira solicitação

curl

curl https://api.vk444.info/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.vk444.info/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.vk444.info/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 chaves API

Ilustração de onda sonora para: Autenticação e chaves API

Para autenticar suas requisições, inclua o cabeçalho Authorization: Bearer <sua-chave> em cada solicitação HTTP. A chave API é um token alfanumérico único que vincula seu uso à conta criada em vk444.info. Utilize este token para garantir que os caracteres consumidos sejam corretamente atribuídos ao seu saldo.

Formato da chave Bearer

Formato da chave Bearer

O protocolo de autenticação segue o padrão OAuth 2.0. Basta inserir sua chave após a palavra Bearer no header da requisição. Exemplo: Authorization: Bearer tts-abc123def456. Não é necessário gerar tokens adicionais para cada endpoint, pois a chave principal valida todas as rotas da API.

Revoque de chave instantânea

Revoque de chave instantânea

Você pode emitir uma nova chave a qualquer momento diretamente no painel. Ao gerar uma nova chave, a anterior é invalidada imediatamente. Isso garante que, em caso de vazamento ou mudança de equipe, o acesso antigo cessa no mesmo instante sem necessidade de espera.

Um token por conta ativa

Cada conta possui apenas uma chave ativa por vez. Isso simplifica a gestão de credenciais em pipelines de automação ou agências que integram a API diretamente em softwares de edição ou produção de áudio. Não há complexidade de rotação de múltiplos tokens simultâneos.

Endpoint principal de síntese

Ilustração de onda sonora para: Endpoint principal de síntese

A síntese de áudio ocorre via endpoint POST https://api.vk444.info/v1/audio/speech. O serviço processa texto e retorna o arquivo de áudio gerado, seguindo a estrutura de requisição padrão do OpenAI Speech.

O limite de entrada é de 4096 caracteres por solicitação. Para textos longos, deve-se dividir o conteúdo em blocos menores e concatenar os arquivos de áudio resultantes.

Método POST /v1/audio/speech

Envie requisições HTTP POST para o endpoint principal. O modelo selecionado ('tts-1' ou 'tts-1-hd') define o motor de síntese e o preço aplicável, ambos com custo idêntico de $0,01 por 1.000 caracteres.

A velocidade pode ser ajustada entre 0.25 e 4.0. O idioma opcional ajuda na precisão; caso não seja definido, o sistema tenta adivinhar com base no script, assumindo inglês para textos em latim.

  • Use o método HTTP POST.
  • Endpoint: /v1/audio/speech.
  • Modelos: tts-1 ou tts-1-hd.

Corpo JSON com input e voice

O corpo da requisição deve conter o campo input com o texto a ser sintetizado e o campo voice com uma das oito vozes disponíveis (ex: 'aria', 'nova', 'luna').

O campo response_format define o formato de saída: mp3, wav, opus, flac ou pcm. Especifique o idioma ISO se necessário para evitar ambiguidades na pronúncia.

  • input: texto (máx. 4096 chars).
  • voice: nome da voz (ex: 'nova').
  • response_format: mp3, wav, opus, flac, pcm.
  • speed: 0.25 a 4.0 (opcional).

Resposta com arquivo de áudio binário

Em caso de sucesso, a resposta contém o arquivo de áudio binário diretamente no corpo. Não há streaming; o arquivo é entregue completo após o processamento.

Se a síntese falhar, o charge é estornado integralmente. O arquivo gerado possui uma marca d'água inaudível que indica ser fala sintetizada.

  • Retorna áudio binário diretamente.
  • Formatos: mp3, wav, opus, flac, pcm.
  • Marca d'água sintética incluída.
  • Falhas resultam em reembolso.

Integração com SDK OpenAI

Ilustração de onda sonora para: Integração com SDK OpenAI

Para integrar o SDK oficial da OpenAI, basta alterar a propriedade base_url para https://api.vk444.info/v1. O formato da requisição é idêntico ao endpoint de speech da OpenAI, permitindo reutilizar clientes existentes sem modificações complexas no código.

Utilize a biblioteca oficial openai do Python ou Node.js. A compatibilidade é direta: o cliente envia o JSON padrão com model, input e voice, recebendo o arquivo de áudio binário na resposta.

Alterar base_url para api.vk444.info

Configure a URL base do cliente para apontar para o endpoint da VoizEngine. Isso redireciona todas as chamadas de síntese para nossa infraestrutura sem alterar a estrutura do payload.

  • Base URL: https://api.vk444.info/v1
  • Formato JSON compatível com OpenAI
  • Sem necessidade de biblioteca própria

Usar cliente OpenAI oficial

Instale a biblioteca oficial da OpenAI (openai). Autentique usando sua chave API VoizEngine no header Authorization: Bearer. O SDK gerencia automaticamente a serialização dos parâmetros.

  • Suporte a Python e Node.js
  • Autenticação via Bearer Token
  • Instalação padrão via pip ou npm

Compatibilidade com métodos existentes

Métodos como audio.speech() funcionam nativamente. Parâmetros como model (tts-1/tts-1-hd), voice e response_format são aceitos sem adaptações. A resposta retorna o áudio bruto, pronto para salvamento.

  • Método POST /v1/audio/speech
  • Parâmetros padrão OpenAI
  • Resposta binária direta

Exemplo de solicitação cURL

Ilustração de onda sonora para: Exemplo de solicitação cURL

O comando cURL abaixo ilustra uma solicitação direta para o endpoint de síntese, utilizando a chave Bearer e especificando parâmetros essenciais como modelo, voz e formato de saída.

Este exemplo é executável em qualquer terminal compatível com HTTP/1.1 e serve como ponto de partida para integrações rápidas com scripts Python ou Bash.

Comando pronto para terminal

Execute o seguinte comando, substituindo <YOUR_API_KEY> pela sua chave ativa. O comando envia um texto curto e retorna o arquivo de áudio no formato especificado.

  • curl -X POST https://api.vk444.info/v1/audio/speech \
  • -H "Authorization: Bearer <YOUR_API_KEY>" \
  • -H "Content-Type: application/json" \
  • -d '{"model": "tts-1", "input": "Olá, esta é uma demonstração rápida.", "voice": "aria", "response_format": "mp3"}' \
  • -o output_audio.mp3

Parâmetros básicos obrigatórios

O corpo JSON requer campos específicos para garantir a síntese correta. O campo 'input' aceita até 4096 caracteres, incluindo espaços e pontuação.

Defina 'model' como 'tts-1' ou 'tts-1-hd'. A 'voice' deve ser um dos 8 presets disponíveis. 'response_format' determina o arquivo gerado (mp3, wav, opus, flac, pcm).

Headers de autenticação

O cabeçalho Authorization deve conter o token Bearer válido. Cada conta possui apenas uma chave ativa por vez; a emissão de uma nova revoga a anterior instantaneamente.

Formatos de saída suportados

Ilustração de onda sonora para: Formatos de saída suportados

O parâmetro response_format define o codec de saída da síntese. A escolha impacta diretamente o tamanho do arquivo e a compatibilidade com seus players ou editores de vídeo.

mp3 para compressão leve

Formato padrão recomendado para a maioria dos fluxos de trabalho. Oferece excelente relação entre qualidade audível e tamanho reduzido, ideal para upload rápido em plataformas de vídeo.

wav para qualidade sem perda

Audio PCM não comprimido. Mantém a fidelidade original da síntese sem redução de bits. Ideal para pós-produção profissional onde você aplicará efeitos ou compressão adicional no editor.

opus, flac e pcm disponíveis

Opus para eficiência em transmissão de áudio. FLAC para arquivamento sem perda. PCM para processamento raw imediato. Selecione conforme sua necessidade de armazenamento ou processamento posterior.

Formatos de saída suportados

Limites e throttling

Ilustração de onda sonora para: Limites e throttling

A API impõe um limite de 60 requisições por minuto por chave de API ativa. Esse limite se aplica simultaneamente a todos os endpoints da API, incluindo síntese de voz e consulta de vozes. O processamento ocorre sequencialmente; em momentos de alta demanda, suas requisições podem aguardar na fila antes da geração do áudio.

60 requisições por minuto por chave

O limite de 60 RPM é aplicado por chave de API, independentemente do número de solicitações simultâneas. Cada chamada para o endpoint POST /v1/audio/speech conta como uma unidade. Se você enviar múltiplas requisições em paralelo, elas serão contadas no mesmo minuto corrente.

  • Limite global por chave: 60 RPM
  • Aplica-se a todos os endpoints
  • Processamento sequencial sujeito a fila

10 req/min antes do primeiro top-up

Novas contas sem saldo topado começam com um limite reduzido de 10 requisições por minuto. Isso permite testar a integração com baixa carga. Após o primeiro depósito via USDT (TRC-20), o limite é elevadocom automaticamente para 60 RPM, sem necessidade de confirmação manual.

  • Limite inicial: 10 RPM
  • Sem saldo topado: limite reduzido
  • Upgrade automático após primeiro depósito

Tratamento de erro 429 Too Many Requests

Quando o limite é excedido, a API retorna o código de status HTTP 429. Inclui um cabeçalho Retry-After indicando segundos para aguardar. Implemente lógica de retry exponencial ou fila de tarefas para gerenciar picos de volume sem perder requisições válidas.

  • Código HTTP: 429
  • Cabeçalho Retry-After presente
  • Recomenda-se retry exponencial

Tratamento de erros comuns

Ilustração de onda sonora para: Tratamento de erros comuns

A API retorna códigos de status HTTP claros para indicar o estado da requisição. O erro 400 sinaliza parâmetros ausentes ou fora do formato esperado, como um texto vazio ou uma voz inexistente no catálogo. O erro 401 indica que o token Bearer está incorreto ou revogado.

Erro de input inválido

Verifique se o campo input está preenchido e respeita o limite de 4096 caracteres. A ausência de um campo obrigatório ou o uso de um voice não listado em /v1/voices gera erro 400. O corpo da resposta inclui detalhes específicos sobre qual parâmetro falhou, facilitando a correção imediata no código.

  • Verifique o tamanho do texto antes do envio
  • Confirme o ID da voz no catálogo

Chave expirada ou inválida

Uma chave inválida retorna erro 401. Lembre-se que emitir uma nova chave revoca a anterior instantaneamente. Se você não reconhece a chave ativa, verifique se há outra sessão usando-a. Renove a chave na página de gestão para obter um token válido imediatamente.

Falha de síntese com reembolso

Se a síntese falhar devido a um erro interno ou indisponibilidade temporária, o status retornado não será de sucesso e o valor correspondente é devolvido integralmente ao seu saldo. Não há cobrança para requisições que não completam a geração do áudio. Verifique os logs para identificar a causa raiz se o erro persistir.

Endpoints auxiliares

Ilustração de onda sonora para: Endpoints auxiliares

Além do endpoint principal de síntese, a API fornece rotas auxiliares para gerenciar recursos e monitorar o consumo. Essas consultas permitem integrar a lista de vozes disponíveis e verificar o status da conta diretamente no painel de controle.

Os endpoints /v1/voices e /v1/models retornam metadados sobre as vozes e modelos suportados, enquanto a consulta de saldo e uso histórico é feita no painel da conta, evitando chamadas API desnecessárias para dados estáticos.

GET /v1/voices para listar vozes

Retorna a lista completa das 8 vozes disponíveis, com seus metadados de idioma e formato. Ideal para popular menus de seleção na interface do usuário antes de enviar a requisição de síntese.

  • Lista vozes, idiomas e formatos compatíveis
  • Útil para validação prévia de parâmetros

GET /v1/models para detalhes técnicos

Exibe informações sobre os modelos tts-1 e tts-1-hd.

Consulta de saldo e uso

Acesse informações de saldo e histórico de consumo diretamente no painel.

Ouça as 8 vozes

Cada amostra abaixo foi gerada por esta API a partir da mesma frase. Testes em diferentes níveis de volume ajudam a identificar vozes que 'cortam' melhor a mixagem.

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. IETF RFC 7845: Ogg Opus
  3. openai-python on GitHub
  4. MDN: Web Speech API
  5. openai-node on GitHub
  6. W3C WAI: making audio and video accessible
  7. Tether (USDT)
  8. Python documentation
  9. TRON developer hub: TRC-20
  10. curl documentation
  11. LibriTTS-R corpus (OpenSLR 141)
  12. LibriVox public-domain audiobooks

Mais neste site