GPT Translator Logo
Ao Vivo & Streaming

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.

Primeiros Passos

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.

Endpoint
wss://api.gpttranslator.co
  └── namespace: /api/realtime-translator
JavaScript — Socket.IO
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.

Node.js backend (server-side)
// 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));
Fluxo da Sessão

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.

1

Iniciar uma sessão

você emite

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

socket.emit('translation_start', { "targetLanguage": "es" });
2

Aguardar sinais de prontidão

você escuta

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

socket.on('session_initializing', callback);
socket.on('translation_ready', callback);
socket.on('ready_for_audio', callback);
3

Transmitir blocos de áudio

você emite

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

socket.emit('audio_chunk', { "audioData": "<base64-pcm16-string>" });
4

Receber saída traduzida

você escuta

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

socket.on('output_audio', callback);
socket.on('output_transcript', callback);
socket.on('input_transcript', callback);
5

Encerrar a sessão

você emite

Emita translation_stop para fechar a sessão corretamente. O uso de tokens é finalizado e um evento translation_closed confirma que a sessão terminou.

socket.emit('translation_stop');
Referência da API

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ê emite
translation_start

Inicia 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_chunk

Envia 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_stop

Encerra a sessão corretamente. O servidor finaliza a cobrança e emite translation_closed.

Eventos que Você Escuta

você escuta
session_initializingstatus

Emitido imediatamente após translation_start. Indica que a sessão está sendo configurada — ainda não pronta para áudio.

translation_readystatus

Emitido assim que a conexão do lado do servidor é estabelecida. Ainda aguardando a ativação final da sessão.

ready_for_audiostatus

A sessão está totalmente ativa. Comece agora a transmitir eventos audio_chunk.

output_audiostream

Um 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_transcriptstream

Um 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_transcriptstream

Um 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_closedstatus

Confirma 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_errorerror

Ocorreu 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_tokenserror

Seu 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 de Código

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.

realtime-translator.js
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');
}
Cobrança

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

1 minuto
~3.000 tokens
Bom para verificações rápidas
5 minutos
~15.000 tokens
Reunião curta ou entrevista
30 minutos
~90.000 tokens
Conversa prolongada
1 hora
~180.000 tokens
Conferência ou palestra
Duração da Sessão
Tokens Aproximados Utilizados
Observações

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.

Guia de Áudio

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.

FormatoPCM 16-bit, little-endian
Taxa de Amostragem24 000 Hz
Canais1 (mono)
Codificação de TransferênciaBase64 string
Captura de microfone do navegador
// 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.