أدلة الوسائط

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

إنشاء الكلام، تحويل الصوت إلى نص، ترجمة الكلام، أو فتح جلسة في الوقت الفعلي

استخدم نقاط نهاية الصوت (audio endpoints) عندما تكون النتيجة ملفاً أو نصاً. استخدم نقطة نهاية WebSocket للوقت الفعلي للحصول على تجربة صوتية حية ثنائية الاتجاه.

اختيار نقطة النهاية

الحاجةنقطة النهايةاستخدمها عندما
تحويل النص إلى كلامPOST /v1/audio/speechتحتاج إلى ملف صوتي من نص.
النسخ الصوتيPOST /v1/audio/transcriptionsتحتاج إلى نص من ملف صوتي.
ترجمة الصوتPOST /v1/audio/translationsتحتاج إلى نص مترجم من ملف صوتي.
WebSocket للوقت الفعليWS /v1/realtime?model={model}تحتاج إلى بث صوتي ثنائي الاتجاه عبر WebSocket. طلب GET /v1/realtime العادي يعيد البيانات الوصفية فقط.

اختيار النموذج

اقرأ قائمة النماذج الحالية بدلاً من كتابتها برمجياً بشكل ثابت (hard-coding). تحقق من تفاصيل النموذج المختار لدعم الوقت الفعلي قبل فتح المقبس (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"

طلبات الصوت

يعيد تحويل النص إلى كلام (Speech) صوتاً في استجابة HTTP. يمكن أن يعيد النسخ الصوتي والترجمة نصاً نهائياً أو مهمة مقبولة. عندما يحتوي النص الأساسي (body) على معرف مهمة (task ID) وحالة بدلاً من النص النهائي، احفظ المعرف وقم بعملية استطلاع (poll) لـ GET /v1/tasks/{id} حتى الاكتمال أو الفشل. اسمح بوقت كافٍ للملفات الكبيرة واحتفظ بمعرف الطلب (Request ID).

عناوين URL لنتائج الصوت هي عناوين URL خاصة بـ TokenLab لنتائج الوسائط تظل صالحة لمدة 30 يوماً. يقوم media_retention.items بالإبلاغ عن حالة حفظ كل عنصر و expires_at؛ قد تغفل الاستجابة media_retention عندما لا تكون حالة الحفظ معروفة في الوقت المناسب، ومع ذلك يظل عنوان URL يعمل. استجابات الصوت المضمنة أو الثنائية تقع خارج نطاق الاحتفاظ بنسخ URL هذه. راجع الاحتفاظ بالبيانات.

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

جلسات الوقت الفعلي

افتح WebSocket مع النموذج في سلسلة استعلام (query string) ومفتاح API في ترويسة Authorization. احتفظ بتنسيق الحدث الموثق لنموذج الوقت الفعلي المختار، وأغلق المقبس عند اكتمال الجلسة.

تستمر الجلسة لمدة ساعة واحدة كحد أقصى. بعد ذلك، يقوم الخادم بإغلاق المقبس بالرمز 1000 والسبب session_timeout. يمكن أن تصل الرسالة الواحدة إلى 32 ميجابايت؛ الرسالة الأكبر تغلق المقبس بالرمز 1009. بعض نماذج الوقت الفعلي، مثل grok-voice-think-fast-2.0، تأخذ إطارات الصوت وتحديثات الجلسة فقط. عنصر إدخال النص يعيد الخطأ unsupported_realtime_text_input ويغلق المقبس بالرمز 1008.

يغطي هذا الدليل مجموعة WebSocket الفرعية فقط. لا توفر TokenLab حالياً سر عميل REST للوقت الفعلي من OpenAI، أو سر عميل الترجمة، أو المكالمات، أو نقاط نهاية إدارة الجلسات التجريبية القديمة.

بالنسبة لمثال جانب الخادم أدناه، قم بتثبيت 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'));

إظهار التقدم بأمان

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

مرجع API

الموضوعالمرجع
إنشاء الكلامإنشاء الكلام
إنشاء النسخ الصوتيإنشاء النسخ الصوتي
إنشاء الترجمةإنشاء الترجمة
WebSocket للوقت الفعليWebSocket للوقت الفعلي
قائمة النماذجقائمة النماذج
الفوترة والأسعارالفوترة والأسعار

في هذه الصفحة