الصوت والوقت الفعلي

Realtime WebSocket

الاتصال بجلسات صوتية في الوقت الفعلي (realtime) عبر WebSocket

GET
/v1/realtime

نظرة عامة

استخدم نقطة النهاية هذه لجلسات الصوت في الوقت الفعلي. يُرجع طلب GET البسيط بيانات وصفية لنقطة النهاية ولا يتطلب API key. يفتح طلب ترقية WebSocket مع ?model={model} جلسة مع النموذج المحدد.

فقط النماذج التي تُدرج تفاصيلها عملية realtime يمكنها فتح جلسة. اقرأ supported_operations في GET /v1/models/{model} قبل الاتصال. تُدرج تفاصيل النموذج نفسها الأحداث والحقول التي تقبلها الجلسة، مثل session.update أو response.create.

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

تُعد GET /v1/realtime مجموعة فرعية من WebSocket. تقوم TokenLab بترحيل أحداث الوقت الفعلي للنموذج المحدد. ولا توفر أدوات OpenAI Realtime REST المساعدة: إنشاء الجلسات، أو client_secrets، أو Calls، أو واجهات برمجة تطبيقات الجلسات القديمة التجريبية (legacy beta session APIs).

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

تستخدم جلسات الوقت الفعلي خيار التسليم الخاص بمفتاح API key أو Workspace. ولا تؤدي ترويسة X-TokenLab-Delivery-Policy أو سلسلة الاستعلام إلى تجاوزه.

الاتصال

modelstringqueryمطلوب

معرّف نموذج الوقت الفعلي. مطلوب لترقية WebSocket.

Authorizationstringheaderمطلوب

Bearer sk-your-api-key، يُرسل مع طلب الترقية. يتم قبول x-api-key أيضًا. لا يُقبل وجود المفتاح في سلسلة الاستعلام.

الطلب

import WebSocket from 'ws';

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', 'grok-voice-latest');

const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${process.env.TOKENLAB_API_KEY}` }
});

socket.on('open', () => console.log('Realtime connection open'));

socket.on('message', (data) => {
  const event = JSON.parse(data.toString());
  if (event.type === 'error') {
    console.error('Realtime error', event.status, event.error.code);
    return;
  }
  console.log('realtime event', event.type);
});

socket.on('close', (code, reason) => console.log('closed', code, reason.toString()));

الرسائل

تقوم TokenLab بترحيل رسائل WebSocket بين عميلك والنموذج. استخدم تنسيق الأحداث الخاص بذلك النموذج، وضع model في سلسلة الاستعلام، وليس في كل حدث. يمكن أن يصل حجم الرسالة إلى 32 MiB كحد أقصى.

الأخطاء

قبل فتح الـ socket، يتم رفض بيانات الاعتماد التي لا تحدد API key صالح للاستخدام مع رمز HTTP 401 أو 403 أو 429 أو 503 ونص خطأ بتنسيق JSON.

بعد فتح الـ socket، تُرسل الجلسة المرفوضة رسالة JSON واحدة ثم تغلق الـ socket:

{
  "type": "error",
  "status": 400,
  "error": {
    "message": "model query parameter is required",
    "type": "invalid_request_error",
    "code": "missing_model"
  }
}
error.codeالسبب
missing_modelمعلَمة الاستعلام model فارغة
unsupported_operationالنموذج غير منشور لـ Realtime API
model_not_allowed، insufficient_balance، quota_exceededلا يمكن للمفتاح استخدام هذا النموذج، أو لا يمكن للرصيد أو حد المفتاح تغطية حجز الجلسة. راجع معالجة أخطاء API

تُغلق الخدمة الـ socket بالرمز 1008 لحالات الرفض هذه. رموز الإغلاق الأخرى: 1009 عندما تكون الرسالة كبيرة جدًا، و1013 عند تراكم الرسائل المتأخرة، و1011 عندما يتعذر على الخدمة توجيه الجلسة أو ترحيلها. تعامل مع الخطأ بناءً على code، وليس على message.

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

تتم فوترة الجلسات خصمًا من رصيد API key الخاص بك. تحجز TokenLab مبلغًا تقديريًا في البداية، ثم تقوم بتسوية الاستخدام الفعلي في النهاية واسترداد الفرق. تتم فوترة النماذج حسب الـ token أو حسب وقت الجلسة، كما هو موضح في تفاصيل النموذج.

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

مثال على الاستجابة

نص JSON أدناه هو الاستجابة لطلب HTTP GET عادي. وهو ليس حدث جلسة.

الاستجابة

HTTP GET
{
  "object": "realtime.endpoint",
  "websocket_url": "/v1/realtime?model={model}",
  "protocol": "tokenlab_realtime_proxy"
}

حقول مهمة

objectstring
realtime.endpoint (عند طلب HTTP GET).
websocket_urlstring
/v1/realtime?model={model} (عند طلب HTTP GET).
protocolstring
tokenlab_realtime_proxy (عند طلب HTTP GET).

التفويض

BearerAuth
AuthorizationBearer <token>

مصادقة مفتاح API. قم بإنشاء أو إدارة مفاتيح API في Dashboard > API > API Keys.

الموضع: header

معاملات الاستعلام

model?string

معرف نموذج الوقت الفعلي. مطلوب لطلبات ترقية WebSocket؛ اختياري لفحوصات بيانات تعريف HTTP العادية.

الاستجابة

application/json

application/json

application/json

application/json

application/json