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.mp3Python (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 | |
|---|---|
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 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
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
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
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
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
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
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.

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
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
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.
23 idiomas
Qualquer voz fala qualquer um desses idiomas.
