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

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

اختيار سير العملCopy Anchor Link

اكتشاف النماذجCopy Anchor Link

استعلم عن كتالوج النماذج قبل تثبيت نموذج في الكود. استخدم القوائم الموصى بها للكلام والتفريغ، وتحقق من دعم الوقت الفعلي في تفاصيل النموذج قبل فتح socket.

curl "https://api.tokenlab.sh/v1/models?recommended_for=tts" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.tokenlab.sh/v1/models?recommended_for=stt" \
  -H "Authorization: Bearer sk-your-api-key"

طلبات الصوت المتزامنةCopy Anchor Link

يعيد تحويل النص إلى كلام الصوت في استجابة HTTP. وقد يعيد التفريغ والترجمة نصًا نهائيًا أو مهمة مقبولة. إذا احتوت الاستجابة على معرّف مهمة وحالتها بدل النص النهائي، فاحفظ المعرّف وتابع poll_url حتى الاكتمال أو الفشل. امنح الملفات الكبيرة مهلة كافية واحتفظ بـ Request ID.

curl -X POST "https://api.tokenlab.sh/v1/audio/speech" \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "tts-1-hd",
    "voice": "nova",
    "input": "Welcome to TokenLab."
  }' \
  --output speech.mp3

جلسات الوقت الفعليCopy Anchor Link

افتح WebSocket مع model في query string ومفتاح API في ترويسة Authorization. استخدم تنسيق الأحداث الموثق للنموذج الفعلي المختار وأغلق socket عند انتهاء الجلسة.

يغطي هذا الدليل سطح WebSocket المحدود فقط (WebSocket subset). لا يوفر TokenLab حالياً مسارات OpenAI Realtime REST الخاصة بـ client secret أو translation client secret أو Calls أو إدارة legacy beta session.

ثبّت ws للمثال الخادمي، واضبط TOKENLAB_REALTIME_MODEL على نموذج حالي تعلن تفاصيله /v1/realtime. وفّر TOKENLAB_API_KEY في بيئة الخادم؛ الاسم وحده لا يثبت دعم الوقت الحقيقي.

npm install ws

import WebSocket from 'ws';

const model = process.env.TOKENLAB_REALTIME_MODEL;
const apiKey = process.env.TOKENLAB_API_KEY;
if (!model || !apiKey) throw new Error('Set TOKENLAB_REALTIME_MODEL and TOKENLAB_API_KEY');

const url = new URL('wss://api.tokenlab.sh/v1/realtime');
url.searchParams.set('model', model);
const socket = new WebSocket(url, {
  headers: { Authorization: `Bearer ${apiKey}` },
});
socket.on('message', (event) => console.log(event.toString()));
socket.on('error', (error) => console.error(error.message));
process.once('SIGINT', () => socket.close(1000, 'Client stopped'));

معالجة الحالةCopy Anchor Link

• احفظ ملفات الصوت الناتجة بدل إعادة نفس الطلب عند التحديث.
• للتفريغ والترجمة، اعرض حالات الرفع والمعالجة حتى عندما يكون استدعاء API متزامنًا.
• في الوقت الفعلي، عالج أحداث الإغلاق ولا تعاود الاتصال إلا عندما يبدأ المستخدم جلسة جديدة.
• لا تضع مفاتيح API أو URLs خاصة أو أسرار الحساب في نص الصوت.

مرجع APICopy Anchor Link