GPT Translator Logo
En Vivo y Streaming

API de Traducción en Tiempo Real

Añade traducción de voz a voz en vivo a cualquier aplicación en minutos. Envía audio en streaming y recibe audio traducido y transcripciones — todo a través de una única conexión WebSocket.

¿Por qué la API de Traducción en Tiempo Real?

Diseñada para aplicaciones que necesitan traducción instantánea y continua. Una sola conexión persistente maneja toda la sesión — sin polling, sin retrasos y sin complejidad.

Latencia Ultra Baja

El audio en streaming se traduce y devuelve en tiempo real. Sin viajes de ida y vuelta de solicitud-respuesta — los resultados llegan mientras el hablante está hablando.

Entrada y Salida de Audio

Envía audio bruto del micrófono y recibe el habla traducida. Tanto las transcripciones de entrada como las de salida también se transmiten para que puedas mostrar subtítulos en vivo.

Más de 130 Idiomas

Traduce a cualquier idioma principal usando códigos de idioma estándar BCP-47. Cambia los idiomas de destino entre sesiones sin modificar el SDK.

Seguro por Defecto

Cada conexión se autentica con tu token JWT. Las sesiones están aisladas por usuario — tu audio nunca se comparte ni se almacena.

Primeros Pasos

Conectar y Autenticar

La API de Traducción en Tiempo Real funciona sobre un namespace dedicado de Socket.IO. Pasa tu clave API como parámetro de consulta al crear la conexión — el servidor la valida antes de que cualquier sesión pueda comenzar.

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
  },
});

Nota: Obtén tu clave API desde el panel de GPT Translator en la sección API Keys. Las conexiones sin una clave API válida se rechazan inmediatamente.

Nunca expongas tu clave API en el código del cliente

El ejemplo de código anterior es solo para fines ilustrativos. Incrustar tu clave API directamente en JavaScript del navegador la expone a cualquiera que inspeccione el código fuente de tu página o el tráfico de red — cualquiera podría usar tu clave y agotar tu saldo de tokens.

Recomendado: usar un proxy a través de tu propio backend

Tu servidor mantiene la clave API segura y abre la conexión Socket.IO en nombre del navegador. El navegador se conecta a tu servidor, nunca directamente a la API de traducción.

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));
Flujo de Sesión

Ciclo de Vida de la Sesión

Cada sesión de traducción sigue una simple secuencia de cinco pasos. Comprender este orden te ayudará a construir una integración sólida.

1

Iniciar una sesión

tú emites

Emite translation_start con el código del idioma de destino. El servidor reserva tu saldo de tokens y comienza a inicializar la sesión.

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

Esperar señales de disponibilidad

tú escuchas

El servidor emite tres eventos de estado en orden: session_initializing, translation_ready y finalmente ready_for_audio. Comienza a enviar audio solo después de ready_for_audio.

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

Transmitir fragmentos de audio

tú emites

Emite continuamente eventos audio_chunk con audio PCM16 codificado en base64 capturado desde el micrófono. Mantén los fragmentos pequeños (alrededor de 100 ms cada uno) para obtener la menor latencia posible.

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

Recibir salida traducida

tú escuchas

Mientras ocurre la traducción, el servidor transmite output_audio (voz traducida), output_transcript (texto traducido) e input_transcript (texto fuente reconocido) — todo como deltas incrementales.

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

Finalizar la sesión

tú emites

Emite translation_stop para cerrar la sesión correctamente. El uso de tokens se finaliza y un evento translation_closed confirma que la sesión ha terminado.

socket.emit('translation_stop');
Referencia de API

Referencia de Eventos

Una referencia completa de cada evento en la API de Traducción en Tiempo Real — lo que envías y lo que recibes.

Eventos que Envías

tú emites
translation_start

Inicia una nueva sesión de traducción. Pasa el código de idioma BCP-47 para el idioma de destino.

{
  "targetLanguage": "es"  // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}
audio_chunk

Envía un fragmento de audio bruto del micrófono. El campo audioData debe ser un buffer de audio PCM16 mono codificado en base64 y muestreado a 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

Finaliza correctamente la sesión. El servidor finaliza la facturación y emite translation_closed.

Eventos que Escuchas

tú escuchas
session_initializingstatus

Emitido inmediatamente después de translation_start. Indica que la sesión se está configurando — todavía no está lista para audio.

translation_readystatus

Emitido una vez que se establece la conexión del lado del servidor. Aún esperando la activación final de la sesión.

ready_for_audiostatus

La sesión está completamente activa. Comienza a transmitir eventos audio_chunk ahora.

output_audiostream

Un fragmento de audio de voz traducida. El delta es un buffer de audio PCM16 codificado en base64. Almacena los deltas consecutivos y reprodúcelos en orden.

{
  "delta": "<base64-encoded PCM16 audio chunk>"
  // Decoded and played directly to the output speaker
  // Arrives incrementally — buffer chunks for smooth playback
}
output_transcriptstream

Un fragmento del texto traducido. Une los deltas para construir la transcripción traducida completa en tu interfaz.

{
  "delta": "Hola, ¿cómo estás?"  // translated text fragment
}
input_transcriptstream

Un fragmento del discurso fuente reconocido. Une los deltas para construir los subtítulos del idioma fuente.

{
  "delta": "Hello, how are you?"  // recognized source speech fragment
}
translation_closedstatus

Confirma que la sesión ha terminado correctamente — ya sea después de translation_stop o cuando el servidor cierra la sesión debido al agotamiento de tokens.

translation_errorerror

Ocurrió un error inesperado. El campo message explica qué salió mal. La sesión puede seguir activa — puedes reintentar o llamar a translation_stop.

{
  "message": "Translation session error. Please try again."
}
insufficient_tokenserror

Tu saldo de tokens se ha agotado. La sesión se cierra automáticamente. Actualiza tu plan para continuar.

{
  "message": "You have reached the limit of words for translation...",
  "remainingTokens": 0
}
Ejemplo de Código

Ejemplo Completo de Integración

Un ejemplo mínimo pero completo en JavaScript que muestra cómo conectarse, iniciar una sesión, transmitir audio, manejar todos los eventos del servidor y detener la sesión correctamente.

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');
}
Facturación

Cómo Funciona la Facturación

La traducción en tiempo real se factura según la duración de la sesión — el tiempo entre la activación de la sesión y translation_stop o el agotamiento de tokens. No hay conteo por carácter o palabra.

Facturación por Segundo

El uso se mide en segundos desde el momento en que tu sesión está completamente activa hasta que termina. Los segundos parciales se redondean hacia arriba.

📊

Tokens Deducidos en Vivo

Los tokens se deducen de tu saldo al final de cada sesión según la duración real. Tu saldo disponible se verifica antes de que una sesión pueda comenzar.

🔒

Límite Automático

La sesión se termina automáticamente cuando tu saldo restante de tokens está por agotarse. Recibirás un evento insufficient_tokens antes de que la sesión se cierre.

Consumo Estimado de Tokens

1 minuto
~3 000 tokens
Bueno para verificaciones rápidas
5 minutos
~15 000 tokens
Reunión corta o entrevista
30 minutos
~90 000 tokens
Conversación extendida
1 hora
~180 000 tokens
Conferencia o clase
Duración de la Sesión
Tokens Aproximados Utilizados
Notas

Nota: Las estimaciones de tokens son aproximadas. El consumo real depende de los niveles de ruido del audio y de la actividad de la sesión. Consulta tu panel para ver el uso en tiempo real.

Guía de Audio

Requisitos del Formato de Audio

La API espera un formato de audio específico para obtener la mejor precisión y la menor latencia. Usa el fragmento de código a continuación para capturar y convertir audio del micrófono en el navegador.

FormatoPCM 16-bit, little-endian
Frecuencia de Muestreo24 000 Hz
Canales1 (mono)
Codificación de TransferenciaBase64 string
Captura de micrófono del 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);

Preguntas Frecuentes

Preguntas comunes sobre la integración y el uso de la API de Traducción en Tiempo Real.