API de Tradução em Tempo Real
Adicione tradução de fala para fala em tempo real a qualquer aplicativo em minutos. Transmita áudio e receba áudio traduzido e transcrições de volta — tudo através de uma única conexão WebSocket.
Por que a API de Tradução em Tempo Real?
Criada para aplicativos que precisam de tradução instantânea e contínua. Uma única conexão persistente gerencia toda a sessão — sem polling, sem atrasos e sem complexidade.
Latência Ultra Baixa
O áudio em streaming é traduzido e retornado em tempo real. Sem viagens de ida e volta de requisição e resposta — os resultados chegam enquanto a pessoa está falando.
Áudio de Entrada e Saída
Envie áudio bruto do microfone e receba a fala traduzida de volta. As transcrições de entrada e saída também são transmitidas para que você possa exibir legendas ao vivo.
Mais de 130 Idiomas
Traduza para qualquer idioma principal usando códigos de idioma padrão BCP-47. Alterne idiomas de destino entre sessões sem mudanças no SDK.
Seguro por Padrão
Cada conexão é autenticada com seu token JWT. As sessões são isoladas por usuário — seu áudio nunca é compartilhado ou armazenado.
Conectar & Autenticar
A API de Tradução em Tempo Real funciona em um namespace Socket.IO dedicado. Passe sua chave de API como parâmetro de consulta ao criar a conexão — o servidor a valida antes que qualquer sessão possa começar.
wss://api.gpttranslator.co └── namespace: /api/realtime-translator
import { io } from 'socket.io-client'; // Connect to the Realtime Translation namespace const socket = io('https://api.gpttranslator.co/api/realtime-translator', { transports: ['websocket'], query: { apiKey: 'YOUR_API_KEY' // your GPT Translator API key }, });
Observação: Obtenha sua chave de API no painel do GPT Translator na seção API Keys. Conexões sem uma chave de API válida são rejeitadas imediatamente.
Nunca exponha sua chave de API no código do lado do cliente
O exemplo de código acima é apenas ilustrativo. Incorporar sua chave de API diretamente no JavaScript do navegador a expõe a qualquer pessoa que inspecione o código-fonte da página ou o tráfego de rede — qualquer pessoa pode então usar sua chave e consumir todo o seu saldo de tokens.
✅ Recomendado: usar proxy através do seu próprio backend
Seu servidor mantém a chave de API segura e abre a conexão Socket.IO em nome do navegador. O navegador se conecta ao seu servidor, nunca diretamente à API de tradução.
// Your backend holds the key — the browser never sees it
const socket = io('https://api.gpttranslator.co/api/realtime-translator', {
transports: ['websocket'],
query: { apiKey: process.env.GPT_TRANSLATOR_API_KEY },
});
// Proxy events between the browser client and the translation API
browserSocket.on('translation_start', (data) => socket.emit('translation_start', data));
browserSocket.on('audio_chunk', (chunk) => socket.emit('audio_chunk', chunk));
browserSocket.on('translation_stop', () => socket.emit('translation_stop'));
socket.on('output_audio', (data) => browserSocket.emit('output_audio', data));
socket.on('output_transcript', (data) => browserSocket.emit('output_transcript', data));
socket.on('input_transcript', (data) => browserSocket.emit('input_transcript', data));Ciclo de Vida da Sessão
Cada sessão de tradução segue uma sequência simples de cinco etapas. Entender essa ordem ajudará você a criar uma integração robusta.
Iniciar uma sessão
você emiteEmita translation_start com o código do idioma de destino. O servidor reserva seu saldo de tokens e começa a inicializar a sessão.
Aguardar sinais de prontidão
você escutaO servidor emite três eventos de status em ordem: session_initializing, translation_ready e finalmente ready_for_audio. Comece a enviar áudio somente após ready_for_audio.
Transmitir blocos de áudio
você emiteEmita continuamente eventos audio_chunk com áudio PCM16 codificado em base64 capturado do microfone. Mantenha os blocos pequenos (cerca de 100 ms cada) para obter a menor latência possível.
Receber saída traduzida
você escutaEnquanto a tradução acontece, o servidor transmite output_audio (fala traduzida), output_transcript (texto traduzido) e input_transcript (texto original reconhecido) — tudo como deltas incrementais.
Encerrar a sessão
você emiteEmita translation_stop para fechar a sessão corretamente. O uso de tokens é finalizado e um evento translation_closed confirma que a sessão terminou.
Referência de Eventos
Uma referência completa de todos os eventos da API de Tradução em Tempo Real — o que você envia e o que recebe.
Eventos que Você Emite
você emitetranslation_startInicia uma nova sessão de tradução. Passe o código de idioma BCP-47 do idioma de destino.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkEnvia um bloco de áudio bruto do microfone. O campo audioData deve ser um buffer de áudio PCM16 mono codificado em base64 com taxa de amostragem de 24.000 Hz.
{
"audioData": "<base64-encoded PCM16 mono audio>"
// Sample rate: 24 000 Hz
// Encoding: 16-bit PCM, little-endian
// Send continuously while the user speaks
}translation_stopEncerra a sessão corretamente. O servidor finaliza a cobrança e emite translation_closed.
Eventos que Você Escuta
você escutasession_initializingstatusEmitido imediatamente após translation_start. Indica que a sessão está sendo configurada — ainda não pronta para áudio.
translation_readystatusEmitido assim que a conexão do lado do servidor é estabelecida. Ainda aguardando a ativação final da sessão.
ready_for_audiostatusA sessão está totalmente ativa. Comece agora a transmitir eventos audio_chunk.
output_audiostreamUm bloco de áudio de fala traduzida. O delta é um buffer de áudio PCM16 codificado em base64. Armazene os deltas consecutivos e reproduza-os em ordem.
{
"delta": "<base64-encoded PCM16 audio chunk>"
// Decoded and played directly to the output speaker
// Arrives incrementally — buffer chunks for smooth playback
}output_transcriptstreamUm fragmento do texto traduzido. Anexe os deltas para construir a transcrição traduzida completa na sua interface.
{
"delta": "Hola, ¿cómo estás?" // translated text fragment
}input_transcriptstreamUm fragmento da fala original reconhecida. Anexe os deltas para construir a legenda no idioma de origem.
{
"delta": "Hello, how are you?" // recognized source speech fragment
}translation_closedstatusConfirma que a sessão terminou corretamente — seja após translation_stop ou quando o servidor fecha a sessão devido ao esgotamento de tokens.
translation_errorerrorOcorreu um erro inesperado. O campo message explica o que deu errado. A sessão ainda pode estar ativa — você pode tentar novamente ou chamar translation_stop.
{
"message": "Translation session error. Please try again."
}insufficient_tokenserrorSeu saldo de tokens acabou. A sessão é fechada automaticamente. Atualize seu plano para continuar.
{
"message": "You have reached the limit of words for translation...",
"remainingTokens": 0
}Exemplo Completo de Integração
Um exemplo JavaScript mínimo, mas completo, mostrando como conectar, iniciar uma sessão, transmitir áudio, lidar com todos os eventos do servidor e encerrar a sessão corretamente.
import { io } from 'socket.io-client';
const socket = io('https://api.gpttranslator.co/api/realtime-translator', {
transports: ['websocket'],
query: { apiKey: 'YOUR_API_KEY' },
});
// ─── Listen for server events ───────────────────────────────────────
socket.on('session_initializing', () => {
console.log('Session is being prepared...');
});
socket.on('translation_ready', () => {
console.log('Session connected. Waiting for activation...');
});
socket.on('ready_for_audio', () => {
console.log('Ready! Start streaming audio chunks now.');
startMicrophone(); // begin capturing and sending audio
});
socket.on('output_audio', ({ delta }) => {
// delta is a base64-encoded PCM16 audio chunk
playAudioChunk(atob(delta));
});
socket.on('output_transcript', ({ delta }) => {
// Append translated text delta to your UI
appendToTranscript('translated', delta);
});
socket.on('input_transcript', ({ delta }) => {
// Append recognized source speech to your UI
appendToTranscript('original', delta);
});
socket.on('translation_closed', () => {
console.log('Session ended.');
stopMicrophone();
});
socket.on('translation_error', ({ message }) => {
console.error('Error:', message);
stopMicrophone();
});
socket.on('insufficient_tokens', ({ message, remainingTokens }) => {
console.warn('Out of tokens:', message, 'remaining:', remainingTokens);
stopMicrophone();
showUpgradePrompt();
});
// ─── Start a session ────────────────────────────────────────────────
socket.emit('translation_start', { targetLanguage: 'es' });
// ─── Stream audio chunks ────────────────────────────────────────────
function onAudioData(pcm16Base64) {
socket.emit('audio_chunk', { audioData: pcm16Base64 });
}
// ─── Stop the session ───────────────────────────────────────────────
function stopSession() {
socket.emit('translation_stop');
}Como Funciona a Cobrança
A tradução em tempo real é cobrada pela duração da sessão — o tempo entre a ativação da sessão e translation_stop ou o esgotamento dos tokens. Não há contagem por caractere ou palavra.
Cobrança por Segundo
O uso é medido em segundos desde o momento em que sua sessão está totalmente ativa até o seu término. Segundos parciais são arredondados para cima.
Tokens Deduzidos em Tempo Real
Os tokens são deduzidos do seu saldo no final de cada sessão com base na duração real. Seu saldo disponível é verificado antes que uma sessão possa começar.
Limite Automático
A sessão é encerrada automaticamente quando o saldo restante de tokens estiver prestes a acabar. Você receberá um evento insufficient_tokens antes do encerramento da sessão.
Consumo Estimado de Tokens
Observação: As estimativas de tokens são aproximadas. O consumo real depende dos níveis de ruído do áudio e da atividade da sessão. Verifique seu painel para uso em tempo real.
Requisitos do Formato de Áudio
A API espera um formato de áudio específico para obter a melhor precisão e a menor latência. Use o trecho de código abaixo para capturar e converter áudio do microfone no navegador.
PCM 16-bit, little-endian24 000 Hz1 (mono)Base64 string// Capture PCM16 audio from the browser microphone
const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
const audioContext = new AudioContext({ sampleRate: 24000 });
const source = audioContext.createMediaStreamSource(stream);
const processor = audioContext.createScriptProcessor(4096, 1, 1);
processor.onaudioprocess = (e) => {
const float32 = e.inputBuffer.getChannelData(0);
// Convert Float32 → Int16 PCM
const int16 = new Int16Array(float32.length);
for (let i = 0; i < float32.length; i++) {
int16[i] = Math.max(-32768, Math.min(32767, float32[i] * 32768));
}
// Base64-encode and send
const base64 = btoa(String.fromCharCode(...new Uint8Array(int16.buffer)));
socket.emit('audio_chunk', { audioData: base64 });
};
source.connect(processor);
processor.connect(audioContext.destination);Perguntas Frequentes
Perguntas comuns sobre integração e uso da API de Tradução em Tempo Real.