نظرة SDK العامة

استخدم هذه الصفحة لاختيار الحمل ووقت التشغيل، ثم انتقل إلى دليل JavaScript أو Python للاطلاع على المنشئات والخيارات وحقول الاستجابة وثوابت الأحداث والبرامج المختبرة بدقة. يصدر Go SDK من العقد نفسه، ويشير الرابط أدناه إلى توثيق مصدره.

اختر حسب المهمة

ابدأ من شكل الصوت، لا من اسم العميل:

النسخ السريع مخصص لوحدة مكتملة ومحدودة وحساسة لزمن الاستجابة. ليس هو المسار لتسجيل طويل أو بودكاست؛ استخدم Batch لهذه الأحمال.

يشكّل Subtitles توقيت الكلمات المكتملة بعد اختيار عميل النسخ. يُصدر RealtimeSubtitles أيضًا، لكن إزالة التكرار فيه حسب id:seq تتطلب أن يوفر السلك قيم تسلسل متميزة؛ راجع قسم النهائية أدناه. كلاهما مساعد نتائج وليس عميل نقل.

إذا احتجت إلى بث HTTP مباشر بدل عميل SDK، فاستخدم دليل Realtime HTTP.

اختر وقت تشغيل على الخادم

تعامل مع نتائج سياسة محتوى TTS

تصنف مساعدات JavaScript ‏isTtsCode() وisTtsOwned()، ومساعدات Python ‏is_tts_code() وis_tts_owned()، ومساعدات Go ‏IsTTSCode() وIsTTSOwned() الرمزين على أنهما مملوكان لـTTS. احتفظ بالاستدعاء المنظم قبل أن يرفض استدعاء التوليف بخطئه العام الذي يحتفظ بالرسالة فقط.

لا تنشر حزمة JavaScript حدًا أدنى لإصدار Node.js أو Bun. تعمل أمثلة الوثائق باستخدام Node.js 24 وBun 1.3.14؛ تصف هذه الإصدارات بيئة تحقق الوثائق وليست وعد دعم من SDK.

استخدم humain_voice في شيفرة Python الجديدة. تبقى مساحة sautech التاريخية في 0.18.0 استيراد توافق وتصدر تحذير إهمال.

اضبط الإصدار 0.18.0

اضبط القيم الصادرة لبيئتك في وقت تشغيل موثوق على الخادم:

export API_URL="https://api.voice.humain.com"
export API_KEY="YOUR_API_KEY"
export API_VERSION="v1"

يستخدم Batch القيم API_URL وAPI_KEY وAPI_VERSION. ويتطلب عملاء Socket.IO القيمتين API_URL وAPI_KEY فقط ويستخدمون /socket.io افتراضيًا. اضبط API_PATH فقط عندما يستخدم النشر مسارًا مخصصًا؛ وتتطلب نقطة النهاية القديمة sautech.humain.com المسار /realtime/socket.io.

راجع المصادقة لمسار بيانات الاعتماد في مؤسستك والتعامل مع المفتاح على الخادم.

امتلك دورة الحياة والمهل

أغلق التدفق وعميله

عادة يحرر إغلاق التدفق الناجح جلسة Socket.IO عندما لا تبقى سياقات للطلبات. قد يزيل الخطأ الموجه سياق الطلب قبل تشغيل close()، لذلك يجب أن ينظف النطاق المالك العميل رغم ذلك.

استخدم finally لعملاء JavaScript. وفي Python، استخدم مدير السياق غير المتزامن أو المتزامن المدعوم حيث يوضحه دليل اللغة. أوقف إرسال الصوت بعد الخطأ وافصل الاتصال حتى إذا عاد إغلاق التدفق نفسه بالفعل.

اضبط مهلة لكل عملية

• Batch: يستعلم transcribe كل ثانيتين مع حد افتراضي لحلقة الاستعلام قدره 300 ثانية. قد يمدد الإرسال أو طلب قيد التنفيذ المدة الفعلية؛ ولا يتوقف المساعد المنشور عند cleared بل يصل إلى الحد.
• النسخ السريع: لا تملك JavaScript خيار مهلة للطلب في SDK. القيمة الافتراضية في Python هي 60 ثانية. احتفظ بمهلة تطبيق في وقتي التشغيل.
• Realtime ASR: ينتظر إغلاق التدفق النتيجة النهائية حتى ثانية واحدة افتراضيًا. ينهي انتهاء المهلة الانتظار، لكنه لا يثبت وصول نتيجة نهائية.
• التمييز الفوري: ينتظر الإغلاق حتى خمس ثوان ويعيد أفضل خط زمني موفق معروف إذا انتهى انتظار النتيجة النهائية.
• قائمة الأصوات وTTS: القيم الافتراضية في JavaScript هي خمس ثوان لقائمة الأصوات و30 ثانية من الخمول للتوليف. لا تطبق Python مهلة ما لم تمرر واحدة. هذه ضوابط للعميل؛ ويفرض الخادم أيضًا مهلة كلية غير قابلة لإعادة الضبط قدرها 25 ثانية ومراقب خمول قدره 60 ثانية. تعامل مع قائمة أصوات فارغة وأغلق العميل في وقتي التشغيل.

فسّر النتائج حسب المرحلة

ميّز النتائج المؤقتة والطرفية

• Batch: اعتبر done وfailed وcleared حالات طرفية في مستعلم يملكه التطبيق. ينجح مساعد transcribe المنشور عند done، ويرفع خطأً عند failed، ولا ينتهي مبكرًا عند cleared.
• النسخ السريع: استخدم is_final لاستبدال النص الجزئي بالنتيجة النهائية للوحدة الصوتية المكتملة.
• Realtime ASR: تكون النتيجة مؤقتة ما دام is_final وis_speech_final كلاهما false. استبدل نص واجهة الاستخدام المؤقت بدل إلحاقه كنسخة ثانية.
• التمييز الفوري: تمثل segments الخط الزمني الموفق؛ لا يمثل newlyFinalized / newly_finalized سوى الزيادة النهائية الجديدة.
• TTS: اجمع الصوت أو ابثه حتى is_last؛ البايتات المعادة PCM16 خام وليست حاوية WAV.

أنشئ الترجمات من التوقيت النهائي فقط

يقرأ Subtitles.fromResponse() في JavaScript وresult.subtitles() في Python إزاحات الكلمات الموحدة ويولدان SRT أو WebVTT. يتجاهل RealtimeSubtitles الاستجابات الجزئية ويزيل تكرار الاستجابات النهائية حسب id:seq. لا يضمن عقد Realtime السلكي الحالي قيم seq متميزة، لذلك اجمع كلمات الأحداث النهائية بترتيب الوصول واعرضها باستخدام Subtitles عندما يمكن أن ينتج التدفق عدة أحداث نهائية. يبقى النص المؤقت على الشاشة مسؤولية التطبيق.

مقاطع المتحدثين مخرج مختلف. صدّرها عبر toRttm() في JavaScript أو to_rttm() في Python، أو وفقها مع كلمات ASR النهائية عند إنشاء ترجمات منسوبة إلى المتحدثين.

احتفظ بالأخطاء المنظمة قبل إعادة المحاولة

تعرض استثناءات Batch HTTP حقول الحالة والرمز وقابلية إعادة المحاولة والسعة وتأخير الإعادة مع استخدام statusCode / retryAfter في JavaScript و status_code / retry_after في Python عند توفرها.

يمكن لاستدعاءات أخطاء النسخ السريع وTTS الاحتفاظ بكائن ErrorResponse منظم. تستخدم وعود JavaScript أو استدعاءات Python المرفوضة أخطاء عامة تحمل الرسالة فقط في مسار الفشل الموجه، لذلك سجل حقول الاستدعاء المنظمة قبل التنظيف.

maxRetries / max_retries مهمل ومتجاهل في 0.18.0. أضف سياسة إعادة محاولة محدودة في التطبيق، ولا تكرر رفعًا غامض النتيجة بلا تمييز. راجع الأخطاء وحدود المعدل.

الخطوات التالية

اختر دليلًا واتبع برنامجه المختبر للعميل المحدد. صفحات اللغة هي مرجع العمليات العامة الدقيقة والتنظيف الخاص باللغة؛ أما هذه النظرة فهي خريطة القرار.