> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tokenlab.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# Realtime WebSocket

> الاتصال بجلسات صوتية ومتعددة الوسائط فورية عبر WebSocket

## نظرة عامة

يستخدم هذا المسار لجلسات التعرف على الكلام، توليد الكلام، ترجمة الكلام، أو النماذج متعددة الوسائط الفورية. طلب `GET` العادي يعيد معلومات المسار؛ أما ترقية WebSocket فتُمرر إلى جلسة المزود المختارة.

## النطاق المدعوم

هذا المسار هو وكيل WebSocket الفوري في TokenLab. يدعم فحص metadata عبر `GET /v1/realtime` وترقية WebSocket على المسار نفسه. لا يوفّر مسارات REST المساعدة في OpenAI Realtime مثل `POST /v1/realtime/client_secrets` أو `POST /v1/realtime/translations/client_secrets` أو Realtime Calls (`accept`, `hangup`, `refer`, `reject`) أو إنشاء legacy beta REST session / transcription-session.

في تطبيقات المتصفح أو الجوال، احتفظ بمفاتيح API طويلة العمر على الخادم. هذا المسار لا يصدر Realtime client secrets قصيرة العمر.

<Note>على الوكلاء اكتشاف النماذج التي تدعم realtime عبر `/v1/models` قبل فتح socket.</Note>

## الاتصال

<ParamField query="model" type="string" required>
  معرّف نموذج realtime. استخدم نموذجاً يعلن عقده العام دعم realtime.
</ParamField>

<ParamField header="Authorization" type="string" required>
  مفتاح API بصيغة Bearer. يجب أن يرسل عميل WebSocket ترويسة `Authorization: Bearer sk-your-api-key` أثناء طلب الترقية.
</ParamField>

<RequestExample>
  ```javascript JavaScript theme={null}
  import WebSocket from 'ws';

  const socket = new WebSocket('wss://api.tokenlab.sh/v1/realtime?model=gpt-realtime', {
    headers: { Authorization: 'Bearer sk-your-api-key' }
  });

  socket.on('open', () => {
    socket.send(JSON.stringify({
      type: 'session.update',
      session: { modalities: ['text', 'audio'] }
    }));
  });

  socket.on('message', (data) => {
    console.log('realtime event', data.toString());
  });
  ```

  ```bash cURL theme={null}
  curl "https://api.tokenlab.sh/v1/realtime" \
    -H "Authorization: Bearer sk-your-api-key"
  ```
</RequestExample>

## الرسائل

يمرر TokenLab رسائل WebSocket بين عميلك والمزود الفوري الذي تم اختياره. احتفظ بشكل الأحداث الرسمي للنموذج المحدد ومرر `model` في query string.

## الفوترة والإغلاق

تستخدم جلسات realtime رصيد مفتاح API نفسه. يخصم TokenLab تقديراً صغيراً عند فتح socket، ثم يسوي المبلغ أو يرده عند الإغلاق.

أغلق socket العميل عند اكتمال الجلسة. إذا أغلق المزود أولاً، يحاول TokenLab تمرير رمز الإغلاق إلى العميل.

## مثال الاستجابة

<ResponseExample>
  ```json Connected theme={null}
  {
    "type": "session.created",
    "session": {
      "id": "sess_abc123",
      "model": "gpt-realtime",
      "modalities": ["text", "audio"]
    }
  }
  ```
</ResponseExample>

## حقول مهمة

<ResponseField name="type" type="string">نوع الحدث أو الرسالة الذي تعيده API.</ResponseField>
<ResponseField name="session.id" type="string">معرّف يصدره مزود الوقت الفعلي؛ ضمّنه في سجلات الدعم، وليس كعنوان URL لجلسة REST.</ResponseField>