Gerçek Zamanlı Çeviri API’si
Dakikalar içinde herhangi bir uygulamaya canlı konuşmadan konuşmaya çeviri ekleyin. Ses akışı gönderin ve çevrilmiş ses ile transkriptleri geri alın — hepsi tek bir WebSocket bağlantısı üzerinden.
Neden Gerçek Zamanlı Çeviri API’si?
Anlık ve sürekli çeviri gerektiren uygulamalar için geliştirildi. Tek bir kalıcı bağlantı tüm oturumu yönetir — polling yok, gecikme yok, karmaşıklık yok.
Ultra Düşük Gecikme
Akış halindeki ses gerçek zamanlı olarak çevrilir ve geri gönderilir. İstek-cevap döngüleri yoktur — sonuçlar konuşmacı konuşurken gelir.
Ses Girişi ve Çıkışı
Ham mikrofon sesini gönderin ve çevrilmiş konuşmayı geri alın. Hem giriş hem de çıkış transkriptleri de canlı altyazı gösterebilmeniz için akış halinde iletilir.
130+ Dil
Standart BCP-47 dil kodlarını kullanarak tüm büyük dillere çeviri yapın. SDK değişikliği yapmadan oturumlar arasında hedef dili değiştirin.
Varsayılan Olarak Güvenli
Her bağlantı JWT token’ınız ile doğrulanır. Oturumlar kullanıcı bazında izole edilir — sesiniz asla paylaşılmaz veya depolanmaz.
Bağlan ve Kimlik Doğrula
Gerçek Zamanlı Çeviri API’si özel bir Socket.IO namespace’i üzerinden çalışır. Bağlantı oluştururken API anahtarınızı query parametresi olarak gönderin — sunucu, oturum başlamadan önce anahtarı doğrular.
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 }, });
Not: API anahtarınızı GPT Translator panelindeki API Keys bölümünden alın. Geçerli API anahtarı olmayan bağlantılar anında reddedilir.
API anahtarınızı asla istemci tarafı kodunda paylaşmayın
Yukarıdaki kod örneği yalnızca gösterim amaçlıdır. API anahtarınızı doğrudan tarayıcı JavaScript’ine gömmek, sayfa kaynağını veya ağ trafiğini inceleyen herkesin bu anahtarı görmesine neden olur — böylece herkes anahtarınızı kullanarak token bakiyenizi tüketebilir.
✅ Önerilen: kendi backend’iniz üzerinden proxy kullanın
Sunucunuz API anahtarını güvenli bir şekilde saklar ve Socket.IO bağlantısını tarayıcı adına açar. Tarayıcı doğrudan çeviri API’sine değil, sizin sunucunuza bağlanır.
// 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));Oturum Yaşam Döngüsü
Her çeviri oturumu basit bir beş adımlı sırayı takip eder. Bu sırayı anlamak, sağlam bir entegrasyon oluşturmanıza yardımcı olur.
Oturum başlat
siz gönderirsinizHedef dil koduyla birlikte translation_start gönderin. Sunucu token bakiyenizi ayırır ve oturumu başlatmaya başlar.
Hazırlık sinyallerini bekleyin
siz dinlersinizSunucu sırasıyla üç durum olayı gönderir: session_initializing, translation_ready ve son olarak ready_for_audio. Yalnızca ready_for_audio sonrasında ses göndermeye başlayın.
Ses parçalarını akışa gönderin
siz gönderirsinizMikrofondan alınan base64 kodlu PCM16 sesi içeren audio_chunk olaylarını sürekli gönderin. En düşük gecikme için parçaları küçük tutun (yaklaşık 100 ms).
Çevrilmiş çıktıyı alın
siz dinlersinizÇeviri sırasında sunucu output_audio (çevrilmiş konuşma), output_transcript (çevrilmiş metin) ve input_transcript (tanınan kaynak metin) verilerini artımlı deltalar halinde iletir.
Oturumu sonlandır
siz gönderirsinizOturumu düzgün şekilde kapatmak için translation_stop gönderin. Token kullanımı tamamlanır ve translation_closed olayı oturumun sona erdiğini doğrular.
Olay Referansı
Gerçek Zamanlı Çeviri API’sindeki tüm olayların tam referansı — ne gönderdiğiniz ve ne aldığınız.
Gönderdiğiniz Olaylar
siz gönderirsiniztranslation_startYeni bir çeviri oturumu başlatır. Hedef dil için BCP-47 dil kodunu gönderin.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkHam mikrofon sesinin bir parçasını gönderir. audioData alanı, 24.000 Hz örnekleme hızına sahip base64 kodlu PCM16 mono ses buffer’ı olmalıdır.
{
"audioData": "<base64-encoded PCM16 mono audio>"
// Sample rate: 24 000 Hz
// Encoding: 16-bit PCM, little-endian
// Send continuously while the user speaks
}translation_stopOturumu düzgün şekilde sonlandırır. Sunucu faturalandırmayı tamamlar ve translation_closed gönderir.
Dinlediğiniz Olaylar
siz dinlersinizsession_initializingstatustranslation_start sonrasında hemen gönderilir. Oturumun hazırlanmakta olduğunu gösterir — henüz ses için hazır değildir.
translation_readystatusSunucu tarafındaki bağlantı kurulduğunda gönderilir. Nihai oturum aktivasyonu hâlâ beklenmektedir.
ready_for_audiostatusOturum tamamen aktif. Şimdi audio_chunk olaylarını göndermeye başlayın.
output_audiostreamÇevrilmiş konuşma sesinin bir parçası. Delta, base64 kodlu PCM16 ses buffer’ıdır. Ardışık deltaları buffer’layın ve sırayla oynatın.
{
"delta": "<base64-encoded PCM16 audio chunk>"
// Decoded and played directly to the output speaker
// Arrives incrementally — buffer chunks for smooth playback
}output_transcriptstreamÇevrilmiş metnin bir parçası. Arayüzünüzde tam çevrilmiş transkripti oluşturmak için deltaları birleştirin.
{
"delta": "Hola, ¿cómo estás?" // translated text fragment
}input_transcriptstreamTanınan kaynak konuşmanın bir parçası. Kaynak dil altyazısını oluşturmak için deltaları birleştirin.
{
"delta": "Hello, how are you?" // recognized source speech fragment
}translation_closedstatusOturumun düzgün şekilde sona erdiğini doğrular — translation_stop sonrası veya sunucu tokenlar tükendiği için oturumu kapattığında.
translation_errorerrorBeklenmeyen bir hata oluştu. message alanı neyin yanlış gittiğini açıklar. Oturum hâlâ aktif olabilir — yeniden deneyebilir veya translation_stop çağırabilirsiniz.
{
"message": "Translation session error. Please try again."
}insufficient_tokenserrorToken bakiyeniz tükendi. Oturum otomatik olarak kapatıldı. Devam etmek için planınızı yükseltin.
{
"message": "You have reached the limit of words for translation...",
"remainingTokens": 0
}Tam Entegrasyon Örneği
Bağlanmayı, oturum başlatmayı, ses akışı göndermeyi, tüm sunucu olaylarını işlemeyi ve oturumu düzgün şekilde sonlandırmayı gösteren minimal ama eksiksiz bir JavaScript örneği.
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');
}Faturalandırma Nasıl Çalışır
Gerçek zamanlı çeviri, oturum süresine göre ücretlendirilir — oturumun etkinleştirilmesi ile translation_stop veya token tükenmesi arasındaki süre. Karakter veya kelime başına sayım yapılmaz.
Saniye Başına Faturalandırma
Kullanım, oturum tamamen aktif olduğu andan sona erene kadar saniye cinsinden ölçülür. Kısmi saniyeler yukarı yuvarlanır.
Tokenlar Canlı Olarak Düşülür
Tokenlar, her oturumun sonunda gerçek süreye göre bakiyenizden düşülür. Oturum başlamadan önce mevcut bakiyeniz kontrol edilir.
Otomatik Limit
Kalan token bakiyeniz tükenmek üzere olduğunda oturum otomatik olarak sonlandırılır. Oturum kapanmadan önce insufficient_tokens olayı alırsınız.
Tahmini Token Tüketimi
Not: Token tahminleri yaklaşık değerlerdir. Gerçek tüketim ses gürültü seviyelerine ve oturum etkinliğine bağlıdır. Gerçek zamanlı kullanım için panelinizi kontrol edin.
Ses Formatı Gereksinimleri
API, en iyi doğruluk ve en düşük gecikme için belirli bir ses formatı bekler. Tarayıcıda mikrofon sesini yakalamak ve dönüştürmek için aşağıdaki kod örneğini kullanın.
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);Sıkça Sorulan Sorular
Gerçek Zamanlı Çeviri API’sinin entegrasyonu ve kullanımı hakkında yaygın sorular.