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

اختيار سير العمل

سير العملالنقطةاستخدمه عندما
النص إلى كلامPOST /v1/audio/speechتحتاج إلى ملف صوتي من نص.
التفريغPOST /v1/audio/transcriptionsتحتاج إلى نص من ملف صوتي.
ترجمة الصوتPOST /v1/audio/translationsتحتاج إلى نص مترجم من ملف صوتي.
جلسة وقت فعليGET /v1/realtimeتحتاج إلى صوت ثنائي الاتجاه أو أحداث متعددة الوسائط في الوقت الفعلي.

اكتشاف النماذج

استعلم عن كتالوج النماذج قبل تثبيت نموذج في الكود. استخدم القوائم الموصى بها للكلام والتفريغ، وتحقق من دعم الوقت الفعلي في تفاصيل النموذج قبل فتح 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"

طلبات الصوت المتزامنة

تعيد طلبات الكلام والتفريغ والترجمة النتيجة مباشرة من طلب HTTP. قد تستغرق المدخلات الكبيرة وقتًا أطول من مهلات العملاء الشائعة، لذلك عيّن مهلة واسعة واحفظ request IDs للدعم.
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

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

افتح WebSocket مع model في query string ومفتاح API في ترويسة Authorization. استخدم تنسيق الأحداث الموثق للنموذج الفعلي المختار وأغلق socket عند انتهاء الجلسة.
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('message', (event) => console.log(event.toString()));

معالجة الحالة

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

مرجع API

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