أدلة الوسائط
الصوت والوقت الفعلي
إنشاء الكلام، تحويل الصوت إلى نص، ترجمة الكلام، أو فتح جلسة في الوقت الفعلي
استخدم نقاط نهاية الصوت (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 wsimport 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 للوقت الفعلي |
| قائمة النماذج | قائمة النماذج |
| الفوترة والأسعار | الفوترة والأسعار |