واجهة برمجة الترجمة الفورية
أضف ترجمة صوتية مباشرة من لغة إلى أخرى إلى أي تطبيق خلال دقائق. قم ببث الصوت واستقبل الصوت المترجم والنصوص فورياً — كل ذلك عبر اتصال WebSocket واحد.
لماذا واجهة الترجمة الفورية؟
مصممة للتطبيقات التي تحتاج إلى ترجمة فورية ومستمرة. اتصال دائم واحد يدير الجلسة بالكامل — بدون استطلاع متكرر، بدون تأخير، وبدون تعقيد.
زمن استجابة منخفض جداً
يتم ترجمة الصوت المتدفق وإعادته في الوقت الحقيقي. لا توجد جولات طلب واستجابة — تصل النتائج أثناء تحدث المتحدث.
إدخال وإخراج صوتي
أرسل صوت الميكروفون الخام واستقبل الكلام المترجم مباشرة. كما يتم بث النصوص الخاصة بالإدخال والإخراج لعرض الترجمة الحية.
أكثر من 130 لغة
قم بالترجمة إلى أي لغة رئيسية باستخدام رموز اللغة القياسية BCP-47. يمكنك تغيير اللغة المستهدفة بين الجلسات دون تعديل الـ SDK.
آمن بشكل افتراضي
يتم توثيق كل اتصال باستخدام رمز JWT الخاص بك. الجلسات معزولة لكل مستخدم — ولا يتم مشاركة أو تخزين الصوت الخاص بك.
الاتصال والمصادقة
تعمل واجهة الترجمة الفورية عبر مساحة أسماء Socket.IO مخصصة. مرر مفتاح API كمعامل استعلام عند إنشاء الاتصال — ويتحقق الخادم منه قبل بدء أي جلسة.
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. يتم رفض الاتصالات التي لا تحتوي على مفتاح صالح فوراً.
لا تقم أبداً بكشف مفتاح API الخاص بك في كود الواجهة الأمامية
مثال الكود أعلاه مخصص للتوضيح فقط. تضمين مفتاح API مباشرة داخل JavaScript الخاص بالمتصفح يجعله مكشوفاً لأي شخص يفحص مصدر الصفحة أو حركة الشبكة — ويمكن لأي شخص بعدها استخدام مفتاحك واستنزاف رصيد التوكنات الخاص بك.
✅ موصى به: استخدم وسيطاً عبر خادمك الخلفي
يقوم خادمك بحفظ مفتاح API بشكل آمن ويفتح اتصال Socket.IO نيابةً عن المتصفح. يتصل المتصفح بخادمك فقط، وليس مباشرة بواجهة الترجمة.
// 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 وأخيراً ready_for_audio. ابدأ بإرسال الصوت فقط بعد ready_for_audio.
بث مقاطع الصوت
أنت ترسلأرسل باستمرار أحداث audio_chunk مع صوت PCM16 مشفر بـ base64 تم التقاطه من الميكروفون. اجعل المقاطع صغيرة (حوالي 100 مللي ثانية) للحصول على أقل زمن تأخير.
استقبال المخرجات المترجمة
أنت تستمعأثناء الترجمة، يقوم الخادم ببث output_audio (الصوت المترجم) وoutput_transcript (النص المترجم) وinput_transcript (النص الأصلي المعترف به) — جميعها بشكل تدريجي.
إنهاء الجلسة
أنت ترسلأرسل translation_stop لإغلاق الجلسة بشكل آمن. يتم إنهاء احتساب التوكنات ويرسل حدث translation_closed لتأكيد انتهاء الجلسة.
مرجع الأحداث
مرجع كامل لكل حدث في واجهة الترجمة الفورية — ما الذي ترسله وما الذي تستقبله.
الأحداث التي ترسلها
أنت ترسلtranslation_startيبدأ جلسة ترجمة جديدة. مرر رمز لغة BCP-47 للغة المستهدفة.
{
"targetLanguage": "es" // BCP-47 language code (e.g. "fr", "de", "zh", "ja")
}audio_chunkيرسل مقطعاً من صوت الميكروفون الخام. يجب أن يكون الحقل audioData عبارة عن مخزن صوت PCM16 أحادي القناة ومشفر بـ 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 مشفر بـ 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 قبل إغلاق الجلسة.
الاستهلاك التقديري للتوكنات
ملاحظة: تقديرات التوكنات تقريبية. يعتمد الاستهلاك الفعلي على مستوى الضوضاء الصوتية ونشاط الجلسة. تحقق من لوحة التحكم لمعرفة الاستخدام الفعلي في الوقت الحقيقي.
متطلبات تنسيق الصوت
تتوقع الواجهة تنسيق صوت محدداً للحصول على أفضل دقة وأقل زمن تأخير. استخدم المقتطف البرمجي أدناه لالتقاط وتحويل صوت الميكروفون في المتصفح.
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);الأسئلة الشائعة
أسئلة شائعة حول دمج واستخدام واجهة الترجمة الفورية.