API перевода в реальном времени
Добавьте живой перевод речи в речь в любое приложение за считанные минуты. Передавайте аудио и получайте переведённый звук и транскрипции обратно — всё через одно WebSocket-соединение.
Почему API перевода в реальном времени?
Создано для приложений, которым нужен мгновенный и непрерывный перевод. Одно постоянное соединение управляет всей сессией — без polling, задержек и лишней сложности.
Сверхнизкая задержка
Потоковое аудио переводится и возвращается в реальном времени. Никаких циклов запрос-ответ — результаты приходят во время речи говорящего.
Аудио на вход и выход
Отправляйте необработанное аудио с микрофона и получайте переведённую речь обратно. Транскрипции входящего и исходящего текста также передаются потоково, чтобы вы могли показывать живые субтитры.
130+ языков
Переводите на любой основной язык с использованием стандартных языковых кодов BCP-47. Меняйте целевой язык между сессиями без изменений SDK.
Безопасность по умолчанию
Каждое соединение аутентифицируется с помощью вашего JWT-токена. Сессии изолированы для каждого пользователя — ваше аудио никогда не передаётся и не сохраняется.
Подключение и аутентификация
API перевода в реальном времени работает через выделенное пространство имён Socket.IO. Передавайте API-ключ как query-параметр при создании соединения — сервер проверит его до начала сессии.
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 }, });
Примечание: Получите API-ключ в панели GPT Translator в разделе API Keys. Соединения без действительного API-ключа немедленно отклоняются.
Никогда не раскрывайте свой API-ключ в клиентском коде
Пример кода выше приведён только для иллюстрации. Встраивание API-ключа непосредственно в JavaScript браузера делает его доступным для любого, кто проверит исходный код страницы или сетевой трафик — после этого любой сможет использовать ваш ключ и израсходовать ваш баланс токенов.
✅ Рекомендуется: использовать прокси через собственный backend
Ваш сервер безопасно хранит API-ключ и открывает соединение Socket.IO от имени браузера. Браузер подключается к вашему серверу, а не напрямую к API перевода.
// 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));Жизненный цикл сессии
Каждая сессия перевода следует простой последовательности из пяти шагов. Понимание этого порядка поможет вам создать надёжную интеграцию.
Запустите сессию
вы отправляетеОтправьте translation_start с кодом целевого языка. Сервер резервирует ваш баланс токенов и начинает инициализацию сессии.
Дождитесь сигналов готовности
вы слушаетеСервер отправляет три события статуса по порядку: session_initializing, translation_ready и finally ready_for_audio. Начинайте отправлять аудио только после ready_for_audio.
Передавайте аудиофрагменты
вы отправляетеПостоянно отправляйте события audio_chunk с PCM16-аудио, закодированным в base64 и захваченным с микрофона. Держите фрагменты маленькими (около 100 мс) для минимальной задержки.
Получайте переведённый результат
вы слушаетеВо время перевода сервер потоково отправляет output_audio (переведённую речь), output_transcript (переведённый текст) и input_transcript (распознанный исходный текст) — всё в виде инкрементальных дельт.
Завершите сессию
вы отправляетеОтправьте translation_stop для корректного закрытия сессии. Использование токенов будет завершено, а событие translation_closed подтвердит окончание сессии.
Справочник событий
Полный справочник всех событий API перевода в реальном времени — что вы отправляете и что получаете.
События, которые вы отправляете
вы отправляетеtranslation_startЗапускает новую сессию перевода. Передайте языковой код BCP-47 для целевого языка.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkОтправляет фрагмент необработанного аудио с микрофона. Поле audioData должно быть PCM16 mono audio buffer, закодированным в base64, с частотой дискретизации 24 000 Гц.
{
"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Корректно завершает сессию. Сервер завершает биллинг и отправляет translation_closed.
События, которые вы слушаете
вы слушаетеsession_initializingstatusОтправляется сразу после translation_start. Указывает, что сессия настраивается — аудио ещё не готово.
translation_readystatusОтправляется после установления соединения на стороне сервера. Всё ещё ожидается окончательная активация сессии.
ready_for_audiostatusСессия полностью активна. Теперь начинайте потоковую передачу событий audio_chunk.
output_audiostreamФрагмент переведённого аудио речи. Delta представляет собой PCM16 audio buffer, закодированный в base64. Буферизуйте последовательные дельты и воспроизводите их по порядку.
{
"delta": "<base64-encoded PCM16 audio chunk>"
// Decoded and played directly to the output speaker
// Arrives incrementally — buffer chunks for smooth playback
}output_transcriptstreamФрагмент переведённого текста. Объединяйте дельты для построения полного переведённого транскрипта в вашем интерфейсе.
{
"delta": "Hola, ¿cómo estás?" // translated text fragment
}input_transcriptstreamФрагмент распознанной исходной речи. Объединяйте дельты для построения субтитров на исходном языке.
{
"delta": "Hello, how are you?" // recognized source speech fragment
}translation_closedstatusПодтверждает, что сессия завершилась корректно — либо после translation_stop, либо когда сервер закрыл сессию из-за исчерпания токенов.
translation_errorerrorПроизошла неожиданная ошибка. Поле message объясняет, что пошло не так. Сессия всё ещё может быть активной — вы можете повторить попытку или вызвать translation_stop.
{
"message": "Translation session error. Please try again."
}insufficient_tokenserrorВаш баланс токенов исчерпан. Сессия автоматически закрыта. Обновите тарифный план, чтобы продолжить.
{
"message": "You have reached the limit of words for translation...",
"remainingTokens": 0
}Полный пример интеграции
Минимальный, но полный пример JavaScript, показывающий, как подключиться, запустить сессию, передавать аудио, обрабатывать все события сервера и корректно завершить сессию.
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');
}Как работает биллинг
Перевод в реальном времени оплачивается по длительности сессии — времени между активацией сессии и translation_stop или исчерпанием токенов. Никакого подсчёта символов или слов.
Оплата по секундам
Использование измеряется в секундах с момента полной активации сессии до её завершения. Неполные секунды округляются вверх.
Токены списываются в реальном времени
Токены списываются с вашего баланса в конце каждой сессии на основе фактической продолжительности. Перед запуском сессии проверяется доступный баланс.
Автоматическое ограничение
Сессия автоматически завершается, когда оставшийся баланс токенов почти исчерпан. Перед закрытием сессии вы получите событие insufficient_tokens.
Примерное потребление токенов
Примечание: Оценка токенов приблизительна. Фактическое потребление зависит от уровня шума аудио и активности сессии. Проверяйте панель управления для просмотра использования в реальном времени.
Требования к формату аудио
API ожидает определённый формат аудио для лучшей точности и минимальной задержки. Используйте приведённый ниже пример кода для захвата и преобразования аудио с микрофона в браузере.
PCM 16-bit, little-endian24 000 Hz1 (моно)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);Часто задаваемые вопросы
Распространённые вопросы об интеграции и использовании API перевода в реальном времени.