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.
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.
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 }, });
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.
// 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 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.
Iniciar una sesión
tú emitesEmite translation_start con el código del idioma de destino. El servidor reserva tu saldo de tokens y comienza a inicializar la sesión.
Esperar señales de disponibilidad
tú escuchasEl 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.
Transmitir fragmentos de audio
tú emitesEmite 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.
Recibir salida traducida
tú escuchasMientras 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.
Finalizar la sesión
tú emitesEmite 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.
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ú emitestranslation_startInicia 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_chunkEnví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_stopFinaliza correctamente la sesión. El servidor finaliza la facturación y emite translation_closed.
Eventos que Escuchas
tú escuchassession_initializingstatusEmitido inmediatamente después de translation_start. Indica que la sesión se está configurando — todavía no está lista para audio.
translation_readystatusEmitido 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_audiostatusLa sesión está completamente activa. Comienza a transmitir eventos audio_chunk ahora.
output_audiostreamUn 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_transcriptstreamUn 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_transcriptstreamUn 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_closedstatusConfirma 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_errorerrorOcurrió 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_tokenserrorTu 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 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.
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');
}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
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.
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.
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);Preguntas Frecuentes
Preguntas comunes sobre la integración y el uso de la API de Traducción en Tiempo Real.