Reaaliaikainen käännös-API
Lisää reaaliaikainen puheesta puheeksi -käännös mihin tahansa sovellukseen minuuteissa. Suoratoista ääntä sisään ja vastaanota käännetty ääni sekä tekstitykset takaisin — kaikki yhden WebSocket-yhteyden kautta.
Miksi reaaliaikainen käännös-API?
Rakennettu sovelluksille, jotka tarvitsevat välitöntä ja jatkuvaa käännöstä. Yksi pysyvä yhteys hallitsee koko istuntoa — ei pollingia, ei viiveitä eikä monimutkaisuutta.
Erittäin matala viive
Suoratoistettava ääni käännetään ja palautetaan reaaliajassa. Ei pyyntö-vastaus-kierroksia — tulokset saapuvat puhujan puhuessa.
Ääni sisään, ääni ulos
Lähetä raakaa mikrofonin ääntä ja vastaanota käännetty puhe takaisin. Sekä syöte- että tulostetekstitykset suoratoistetaan myös, jotta voit näyttää live-tekstitykset.
Yli 130 kieltä
Käännä mille tahansa pääkielelle käyttämällä standardoituja BCP-47-kielikoodeja. Vaihda kohdekieltä istuntojen välillä ilman SDK-muutoksia.
Turvallinen oletuksena
Jokainen yhteys todennetaan JWT-tokenillasi. Istunnot ovat eristettyjä käyttäjäkohtaisesti — ääntäsi ei koskaan jaeta tai tallenneta.
Yhdistä ja todenna
Reaaliaikainen käännös-API toimii erillisen Socket.IO-nimiavaruuden kautta. Välitä API-avain kyselyparametrina yhteyttä luotaessa — palvelin tarkistaa sen ennen kuin istunto voi alkaa.
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 }, });
Huomautus: Hanki API-avaimesi GPT Translator -hallintapaneelin API Keys -osiosta. Yhteydet ilman kelvollista API-avainta hylätään välittömästi.
Älä koskaan paljasta API-avaintasi asiakaspuolen koodissa
Yllä oleva koodiesimerkki on tarkoitettu vain havainnollistamiseen. API-avaimen upottaminen suoraan selaimen JavaScriptiin altistaa sen kaikille, jotka tarkastelevat sivun lähdekoodia tai verkkoliikennettä — kuka tahansa voi käyttää avaintasi ja kuluttaa token-saldosi loppuun.
✅ Suositus: käytä välityspalvelinta oman taustajärjestelmäsi kautta
Palvelimesi säilyttää API-avaimen turvallisesti ja avaa Socket.IO-yhteyden selaimen puolesta. Selain muodostaa yhteyden omaan palvelimeesi, ei koskaan suoraan käännös-APIin.
// 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));Istunnon elinkaari
Jokainen käännösistunto seuraa yksinkertaista viiden vaiheen järjestystä. Tämän järjestyksen ymmärtäminen auttaa rakentamaan luotettavan integraation.
Aloita istunto
lähetätLähetä translation_start kohdekielen koodilla. Palvelin varaa token-saldosi ja alkaa alustaa istuntoa.
Odota valmiussignaaleja
kuunteletPalvelin lähettää kolme tilatapahtumaa järjestyksessä: session_initializing, translation_ready ja lopuksi ready_for_audio. Aloita äänen lähettäminen vasta ready_for_audio-tapahtuman jälkeen.
Suoratoista äänipaloja
lähetätLähetä jatkuvasti audio_chunk-tapahtumia, jotka sisältävät base64-koodattua PCM16-ääntä mikrofonista. Pidä palat pieninä (noin 100 ms) pienimmän viiveen saavuttamiseksi.
Vastaanota käännetty tulos
kuunteletKäännöksen aikana palvelin suoratoistaa output_audio (käännetty puhe), output_transcript (käännetty teksti) ja input_transcript (tunnistettu lähdeteksti) — kaikki asteittaisina delta-päivityksinä.
Lopeta istunto
lähetätLähetä translation_stop sulkeaksesi istunnon hallitusti. Token-käyttö viimeistellään ja translation_closed-tapahtuma vahvistaa istunnon päättymisen.
Tapahtumaviite
Täydellinen viite kaikista reaaliaikaisen käännös-API:n tapahtumista — mitä lähetät ja mitä vastaanotat.
Lähettämäsi tapahtumat
lähetättranslation_startKäynnistää uuden käännösistunnon. Välitä kohdekielen BCP-47-kielikoodi.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkLähettää palan raakaa mikrofoniääntä. audioData-kentän tulee olla base64-koodattu PCM16-monoäänipuskuri, jonka näytteenottotaajuus on 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_stopPäättää istunnon hallitusti. Palvelin viimeistelee laskutuksen ja lähettää translation_closed-tapahtuman.
Tapahtumat joita kuuntelet
kuunteletsession_initializingstatusLähetetään välittömästi translation_start-tapahtuman jälkeen. Osoittaa, että istuntoa valmistellaan — ääni ei ole vielä valmis.
translation_readystatusLähetetään, kun palvelinpuolen yhteys on muodostettu. Lopullista istunnon aktivointia vielä odotetaan.
ready_for_audiostatusIstunto on täysin aktiivinen. Aloita nyt audio_chunk-tapahtumien suoratoisto.
output_audiostreamPala käännettyä puheääntä. Delta on base64-koodattu PCM16-äänipuskuri. Puskuroi peräkkäiset deltamuutokset ja toista ne järjestyksessä.
{
"delta": "<base64-encoded PCM16 audio chunk>"
// Decoded and played directly to the output speaker
// Arrives incrementally — buffer chunks for smooth playback
}output_transcriptstreamKatkelma käännetystä tekstistä. Yhdistä deltamuutokset rakentaaksesi täydellisen käännetyn tekstityksen käyttöliittymässäsi.
{
"delta": "Hola, ¿cómo estás?" // translated text fragment
}input_transcriptstreamKatkelma tunnistetusta lähdepuheesta. Yhdistä deltamuutokset rakentaaksesi lähdekielen tekstityksen.
{
"delta": "Hello, how are you?" // recognized source speech fragment
}translation_closedstatusVahvistaa, että istunto on päättynyt siististi — joko translation_stop-tapahtuman jälkeen tai palvelimen sulkiessa istunnon tokenien loppumisen vuoksi.
translation_errorerrorTapahtui odottamaton virhe. message-kenttä selittää, mikä meni pieleen. Istunto voi edelleen olla aktiivinen — voit yrittää uudelleen tai kutsua translation_stop.
{
"message": "Translation session error. Please try again."
}insufficient_tokenserrorToken-saldosi on loppunut. Istunto suljetaan automaattisesti. Päivitä tilauksesi jatkaaksesi.
{
"message": "You have reached the limit of words for translation...",
"remainingTokens": 0
}Täydellinen integraatioesimerkki
Pieni mutta täydellinen JavaScript-esimerkki, joka näyttää kuinka muodostaa yhteys, aloittaa istunto, suoratoistaa ääntä, käsitellä kaikki palvelintapahtumat ja lopettaa istunto siististi.
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');
}Kuinka laskutus toimii
Reaaliaikainen käännös laskutetaan istunnon keston mukaan — aika istunnon aktivoinnista translation_stop-tapahtumaan tai tokenien loppumiseen asti. Ei merkki- tai sanakohtaista laskutusta.
Sekuntiperusteinen laskutus
Käyttö mitataan sekunneissa siitä hetkestä, kun istunto on täysin aktiivinen, siihen asti kunnes se päättyy. Osittaiset sekunnit pyöristetään ylöspäin.
Tokenit vähennetään reaaliajassa
Tokenit vähennetään saldostasi jokaisen istunnon lopussa todellisen keston perusteella. Käytettävissä oleva saldosi tarkistetaan ennen kuin istunto voi alkaa.
Automaattinen rajoitus
Istunto lopetetaan automaattisesti, kun jäljellä oleva token-saldosi olisi loppumassa. Saat insufficient_tokens-tapahtuman ennen istunnon sulkemista.
Arvioitu token-kulutus
Huomautus: Token-arviot ovat suuntaa antavia. Todellinen kulutus riippuu äänen melutasosta ja istunnon aktiivisuudesta. Tarkista reaaliaikainen käyttö hallintapaneelistasi.
Äänimuodon vaatimukset
API odottaa tiettyä äänimuotoa parhaan tarkkuuden ja pienimmän viiveen saavuttamiseksi. Käytä alla olevaa koodiesimerkkiä mikrofoniäänen tallentamiseen ja muuntamiseen selaimessa.
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);Usein kysytyt kysymykset
Yleisiä kysymyksiä reaaliaikaisen käännös-API:n integroinnista ja käytöstä.