GPT Translator Logo
مباشر ومتدفق

واجهة برمجة الترجمة الفورية

أضف ترجمة صوتية مباشرة من لغة إلى أخرى إلى أي تطبيق خلال دقائق. قم ببث الصوت واستقبل الصوت المترجم والنصوص فورياً — كل ذلك عبر اتصال WebSocket واحد.

لماذا واجهة الترجمة الفورية؟

مصممة للتطبيقات التي تحتاج إلى ترجمة فورية ومستمرة. اتصال دائم واحد يدير الجلسة بالكامل — بدون استطلاع متكرر، بدون تأخير، وبدون تعقيد.

زمن استجابة منخفض جداً

يتم ترجمة الصوت المتدفق وإعادته في الوقت الحقيقي. لا توجد جولات طلب واستجابة — تصل النتائج أثناء تحدث المتحدث.

إدخال وإخراج صوتي

أرسل صوت الميكروفون الخام واستقبل الكلام المترجم مباشرة. كما يتم بث النصوص الخاصة بالإدخال والإخراج لعرض الترجمة الحية.

أكثر من 130 لغة

قم بالترجمة إلى أي لغة رئيسية باستخدام رموز اللغة القياسية BCP-47. يمكنك تغيير اللغة المستهدفة بين الجلسات دون تعديل الـ SDK.

آمن بشكل افتراضي

يتم توثيق كل اتصال باستخدام رمز JWT الخاص بك. الجلسات معزولة لكل مستخدم — ولا يتم مشاركة أو تخزين الصوت الخاص بك.

البدء

الاتصال والمصادقة

تعمل واجهة الترجمة الفورية عبر مساحة أسماء Socket.IO مخصصة. مرر مفتاح API كمعامل استعلام عند إنشاء الاتصال — ويتحقق الخادم منه قبل بدء أي جلسة.

نقطة الاتصال
wss://api.gpttranslator.co
  └── namespace: /api/realtime-translator
JavaScript — Socket.IO
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 نيابةً عن المتصفح. يتصل المتصفح بخادمك فقط، وليس مباشرة بواجهة الترجمة.

Node.js backend (server-side)
// 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));
تدفق الجلسة

دورة حياة الجلسة

تتبع كل جلسة ترجمة تسلسلاً بسيطاً من خمس خطوات. فهم هذا الترتيب يساعدك على بناء تكامل قوي.

1

ابدأ جلسة

أنت ترسل

أرسل translation_start مع رمز اللغة المستهدفة. يقوم الخادم بحجز رصيد التوكنات وبدء تهيئة الجلسة.

socket.emit('translation_start', { "targetLanguage": "es" });
2

انتظر إشارات الجاهزية

أنت تستمع

يرسل الخادم ثلاثة أحداث حالة بالترتيب: session_initializing ثم translation_ready وأخيراً ready_for_audio. ابدأ بإرسال الصوت فقط بعد ready_for_audio.

socket.on('session_initializing', callback);
socket.on('translation_ready', callback);
socket.on('ready_for_audio', callback);
3

بث مقاطع الصوت

أنت ترسل

أرسل باستمرار أحداث audio_chunk مع صوت PCM16 مشفر بـ base64 تم التقاطه من الميكروفون. اجعل المقاطع صغيرة (حوالي 100 مللي ثانية) للحصول على أقل زمن تأخير.

socket.emit('audio_chunk', { "audioData": "<base64-pcm16-string>" });
4

استقبال المخرجات المترجمة

أنت تستمع

أثناء الترجمة، يقوم الخادم ببث output_audio (الصوت المترجم) وoutput_transcript (النص المترجم) وinput_transcript (النص الأصلي المعترف به) — جميعها بشكل تدريجي.

socket.on('output_audio', callback);
socket.on('output_transcript', callback);
socket.on('input_transcript', callback);
5

إنهاء الجلسة

أنت ترسل

أرسل translation_stop لإغلاق الجلسة بشكل آمن. يتم إنهاء احتساب التوكنات ويرسل حدث translation_closed لتأكيد انتهاء الجلسة.

socket.emit('translation_stop');
مرجع API

مرجع الأحداث

مرجع كامل لكل حدث في واجهة الترجمة الفورية — ما الذي ترسله وما الذي تستقبله.

الأحداث التي ترسلها

أنت ترسل
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 بسيط لكنه متكامل يوضح كيفية الاتصال وبدء جلسة وبث الصوت والتعامل مع جميع أحداث الخادم وإنهاء الجلسة بشكل صحيح.

realtime-translator.js
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 قبل إغلاق الجلسة.

الاستهلاك التقديري للتوكنات

دقيقة واحدة
حوالي 3,000 توكن
مناسب للفحوصات السريعة
5 دقائق
حوالي 15,000 توكن
اجتماع أو مقابلة قصيرة
30 دقيقة
حوالي 90,000 توكن
محادثة مطولة
ساعة واحدة
حوالي 180,000 توكن
مؤتمر أو محاضرة
مدة الجلسة
عدد التوكنات التقريبي
ملاحظات

ملاحظة: تقديرات التوكنات تقريبية. يعتمد الاستهلاك الفعلي على مستوى الضوضاء الصوتية ونشاط الجلسة. تحقق من لوحة التحكم لمعرفة الاستخدام الفعلي في الوقت الحقيقي.

دليل الصوت

متطلبات تنسيق الصوت

تتوقع الواجهة تنسيق صوت محدداً للحصول على أفضل دقة وأقل زمن تأخير. استخدم المقتطف البرمجي أدناه لالتقاط وتحويل صوت الميكروفون في المتصفح.

التنسيقPCM 16-bit, little-endian
معدل العينة24 000 Hz
القنوات1 (أحادي)
ترميز النقل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);

الأسئلة الشائعة

أسئلة شائعة حول دمج واستخدام واجهة الترجمة الفورية.