Realtime prekladové API
Pridajte živý preklad reči do reči do akejkoľvek aplikácie za pár minút. Streamujte audio a prijímajte preložený zvuk aj prepisy — všetko cez jedno WebSocket pripojenie.
Prečo realtime prekladové API?
Vytvorené pre aplikácie, ktoré potrebujú okamžitý a nepretržitý preklad. Jedno trvalé pripojenie spravuje celú reláciu — bez pollingu, bez oneskorení a bez zložitosti.
Ultra nízka latencia
Streamované audio sa prekladá a vracia v reálnom čase. Žiadne cykly request-response — výsledky prichádzajú počas hovorenia používateľa.
Audio vstup a výstup
Odosielajte surový zvuk z mikrofónu a prijímajte preloženú reč späť. Prepisy vstupu aj výstupu sa tiež streamujú, takže môžete zobrazovať živé titulky.
Viac ako 130 jazykov
Prekladajte do akéhokoľvek hlavného jazyka pomocou štandardných jazykových kódov BCP-47. Prepínajte cieľové jazyky medzi reláciami bez zmien SDK.
Bezpečné predvolene
Každé pripojenie je autentifikované pomocou vášho JWT tokenu. Relácie sú izolované pre každého používateľa — vaše audio sa nikdy nezdieľa ani neukladá.
Pripojenie a autentifikácia
Realtime prekladové API funguje cez dedikovaný Socket.IO namespace. Pri vytváraní pripojenia odošlite API kľúč ako query parameter — server ho overí ešte pred začatím relácie.
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 }, });
Poznámka: Získajte svoj API kľúč z dashboardu GPT Translator v sekcii API Keys. Pripojenia bez platného API kľúča sú okamžite odmietnuté.
Nikdy nezverejňujte svoj API kľúč v klientskom kóde
Vyššie uvedený príklad kódu slúži len na ilustráciu. Vloženie API kľúča priamo do JavaScriptu v prehliadači ho sprístupní každému, kto skontroluje zdrojový kód stránky alebo sieťovú komunikáciu — ktokoľvek potom môže váš kľúč použiť a vyčerpať váš zostatok tokenov.
✅ Odporúčané: používať proxy cez vlastný backend
Váš server bezpečne uchováva API kľúč a otvára Socket.IO pripojenie v mene prehliadača. Prehliadač sa pripája k vášmu serveru, nikdy nie priamo k prekladovému 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));Životný cyklus relácie
Každá prekladová relácia prechádza jednoduchou päťkrokovou sekvenciou. Pochopenie tohto poradia vám pomôže vytvoriť spoľahlivú integráciu.
Spustite reláciu
odosielateOdošlite translation_start s kódom cieľového jazyka. Server rezervuje váš zostatok tokenov a začne inicializovať reláciu.
Počkajte na signály pripravenosti
počúvateServer odošle tri stavové udalosti v poradí: session_initializing, translation_ready a nakoniec ready_for_audio. Začnite odosielať audio až po udalosti ready_for_audio.
Streamujte audio bloky
odosielatePriebežne odosielajte udalosti audio_chunk s base64-kódovaným PCM16 audiom zachyteným z mikrofónu. Bloky udržiavajte malé (približne 100 ms) pre najnižšiu latenciu.
Prijímajte preložený výstup
počúvatePočas prekladu server streamuje output_audio (preloženú reč), output_transcript (preložený text) a input_transcript (rozpoznaný pôvodný text) — všetko vo forme inkrementálnych delt.
Ukončite reláciu
odosielateOdošlite translation_stop pre korektné ukončenie relácie. Spotreba tokenov sa finalizuje a udalosť translation_closed potvrdí ukončenie relácie.
Referencia udalostí
Kompletná referencia všetkých udalostí v realtime prekladovom API — čo odosielate a čo prijímate.
Udalosti, ktoré odosielate
odosielatetranslation_startSpustí novú prekladovú reláciu. Odošlite jazykový kód BCP-47 pre cieľový jazyk.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkOdošle blok surového zvuku z mikrofónu. Pole audioData musí byť base64-kódovaný PCM16 mono audio buffer so vzorkovacou frekvenciou 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_stopKorektne ukončí reláciu. Server finalizuje účtovanie a odošle translation_closed.
Udalosti, ktoré počúvate
počúvatesession_initializingstatusOdosiela sa okamžite po translation_start. Označuje, že relácia sa pripravuje — ešte nie je pripravená na audio.
translation_readystatusOdosiela sa po vytvorení serverového spojenia. Stále sa čaká na finálnu aktiváciu relácie.
ready_for_audiostatusRelácia je plne aktívna. Teraz začnite streamovať udalosti audio_chunk.
output_audiostreamBlok preloženej reči. Delta je base64-kódovaný PCM16 audio buffer. Ukladajte po sebe idúce delty a prehrávajte ich v poradí.
{
"delta": "<base64-encoded PCM16 audio chunk>"
// Decoded and played directly to the output speaker
// Arrives incrementally — buffer chunks for smooth playback
}output_transcriptstreamFragment preloženého textu. Spájajte delty dohromady a vytvorte kompletný preložený prepis vo vašom UI.
{
"delta": "Hola, ¿cómo estás?" // translated text fragment
}input_transcriptstreamFragment rozpoznanej pôvodnej reči. Spájajte delty dohromady a vytvorte titulky v zdrojovom jazyku.
{
"delta": "Hello, how are you?" // recognized source speech fragment
}translation_closedstatusPotvrdzuje, že relácia bola korektne ukončená — buď po translation_stop, alebo keď server ukončí reláciu kvôli vyčerpaniu tokenov.
translation_errorerrorDošlo k neočakávanej chybe. Pole message vysvetľuje, čo sa pokazilo. Relácia môže byť stále aktívna — môžete to skúsiť znova alebo zavolať translation_stop.
{
"message": "Translation session error. Please try again."
}insufficient_tokenserrorVáš zostatok tokenov je vyčerpaný. Relácia bola automaticky ukončená. Aktualizujte svoj plán, aby ste mohli pokračovať.
{
"message": "You have reached the limit of words for translation...",
"remainingTokens": 0
}Kompletný príklad integrácie
Minimálny, ale kompletný JavaScript príklad ukazujúci, ako sa pripojiť, spustiť reláciu, streamovať audio, spracovať všetky serverové udalosti a korektne ukončiť reláciu.
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');
}Ako funguje účtovanie
Realtime preklad sa účtuje podľa trvania relácie — času medzi aktiváciou relácie a translation_stop alebo vyčerpaním tokenov. Žiadne počítanie znakov ani slov.
Účtovanie za sekundu
Použitie sa meria v sekundách od momentu, keď je relácia plne aktívna, až do jej ukončenia. Čiastočné sekundy sa zaokrúhľujú nahor.
Tokeny sa odpočítavajú naživo
Tokeny sa odpočítajú z vášho zostatku na konci každej relácie podľa jej skutočného trvania. Pred začiatkom relácie sa kontroluje dostupný zostatok.
Automatický limit
Relácia sa automaticky ukončí, keď sa váš zostávajúci zostatok tokenov blíži k nule. Pred ukončením relácie dostanete udalosť insufficient_tokens.
Odhadovaná spotreba tokenov
Poznámka: Odhady tokenov sú približné. Skutočná spotreba závisí od úrovne šumu audia a aktivity relácie. Skontrolujte dashboard pre realtime používanie.
Požiadavky na audio formát
API očakáva konkrétny audio formát pre najlepšiu presnosť a najnižšiu latenciu. Použite nižšie uvedený kód na zachytenie a konverziu zvuku z mikrofónu v prehliadači.
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);Často kladené otázky
Bežné otázky o integrácii a používaní realtime prekladového API.