مرجع أحداث TTS
أحداث Socket.IO لتحويل النص إلى كلام وبث مقاطع صوتية ثنائية.
يستقبل TTS حدث tts بحمولة JSON ويبث الصوت عبر tts_audio. يمكن أيضًا طلب
قائمة الأصوات باستخدام tts_voice_list واستلام tts_voice_list_result.
الاتصال
- المسار:
/socket.io - النقل:
websocketفقط - المصادقة: ترويسة
x-api-key - ترويسة
Origin: مطلوبة على الإنتاج؛ اضبطها علىhttps://api.voice.humain.com
التدفق
الأحداث
| الحدث | الاتجاه | المعنى |
|---|---|---|
tts | العميل إلى الخادم | طلب توليد كلام من نص. |
tts_audio | الخادم إلى العميل | مقطع صوت ثنائي. |
tts_voice_list | العميل إلى الخادم | طلب قائمة الأصوات. |
tts_voice_list_result | الخادم إلى العميل | الهويات السبع متعددة اللغات المتاحة. |
error | الخادم إلى العميل | خطأ منظم. |
حمولة tts
{
"id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"text": "مرحبًا من HUMAIN Voice",
"model": "nebula",
"voice_id": "af52a907-1086-46f7-8f5d-72317875d7bd"
}voice_id وvoice_references اختياريان ومتعارضان. استخدم voice_id عندما
تختار صوتًا من المكتبة، واستخدم voice_references لتكييف الصوت من مراجع صوتية.
ويحدد generation_config.emotion الاختياري الأداء الابتدائي للطلب؛ راجع
المشاعر وأسلوب الإلقاء.
المشاعر وأسلوب الإلقاء
تحدد الوسوم في text طريقة نطق كل جزء: بإحدى 7 مشاعر أو بأحد 5 أساليب إلقاء.
وفي قائمة الأصوات، يبيّن profile.emotions (ويبدأ بـneutral)
وprofile.styles ما يدعمه كل صوت.
الوصفات: المشاعر وأسلوب الإلقاء، أداء صوتي لوكيل دعم، سرد قصة، دع نموذج اللغة يكتب نصًا موسومًا.
المشاعر والأساليب
| النوع | الوسوم |
|---|---|
| المشاعر | [neutral] [happy] [sad] [angry] [fearful] [surprised] [whisper] · neutral هو الافتراضي |
| الأساليب | [news] [storytelling] [advertising] [call_center] [conversational] |
الترميز
| الترميز | الأثر |
|---|---|
[sad] | ينتقل إلى sad من هذه النقطة فصاعدًا. |
<emotion value="sad"/>، <style value="news"/> | مثل [sad] و[news]. |
<emotion value="sad">…</emotion>، <style value="news">…</style> | يُطبَّق على النص المحاط، ثم يُستأنف الأداء الخارجي. يمكن أن تتداخل المقاطع؛ فأغلق كل مقطع بالاسم الذي فتحه. |
"generation_config": { "emotion": "news" } | يحدد الأداء الابتدائي للطلب؛ ثم تبدّل الوسوم الأداء انطلاقًا منه. |
[news] Markets closed higher today. <emotion value="happy">A record day!</emotion> More after the break.القواعد
- لكل جزء من النص أداء واحد: عاطفة أو أسلوب، ولا يجتمعان أبدًا.
- الوسم الأخير هو الذي يسري:
[sad][happy]يُنطق بأداءhappy. - الأسماء لا تتأثر بحالة الأحرف، ولا يعمل إلا الاثنا عشر اسمًا أعلاه. ولا توجد أسماء بديلة:
[Happy]يعمل، و[joyful]لا يعمل. - الاسم غير المعروف بين قوسين معقوفين ليس وسمًا، لذلك يُنطق
[laughter]. أما الاسم غير المعروف فيvalueأو فيgeneration_config.emotionفيُتجاهل. - يُتخطى الأداء الذي لا يدرجه الصوت: يُزال الوسم ويستمر الأداء الحالي.
- لا تُنطق الوسوم ولا تُفوتر، ولا تُحسب في حد الأحرف.
القيود
- مع
voice_referencesتُتخطى الوسوم: فالصوت المستنسخ يتحدث بأدائه الخاص. - تعمل مع العربية والإنجليزية. وتبقى أسماء الوسوم بالإنجليزية في كلتيهما.
أخطاء الترميز
غير قابل لإعادة المحاولة: غيّر الطلب أولًا.
| الرمز | السبب | الإجراء |
|---|---|---|
TTS_EMOTION_MARKUP_INVALID | وسم <emotion …> مشوّه، أو مقطع غير مغلق، أو وسم إغلاق لا يطابق ما فتحه. ويذكر message الموضع بنقاط الترميز. | أصلح الوسم عند ذلك الموضع. |
أما وسم <style المشوّه أو </style> الشارد فليس خطأً: بل يُنطق نصًا.
وعمليات النشر التي تضبط حدودًا للمقاطع تُصدر أيضًا
TTS_EMOTION_SEGMENT_COUNT_EXCEEDED (أجزاء أكثر من المسموح)
وTTS_EMOTION_SEGMENT_TOO_SHORT (جزء أقصر من الحد الأدنى)، وكلاهما مع data.
حدود النص
يُحسب طول text بنقاط ترميز Unicode، لا ببايتات UTF-8 ولا بعناقيد المحارف
المعروضة؛ وتُحفظ المسافات في البداية والنهاية وتُحسب. والافتراضيات الشاملة هي
500 نقطة ترميز للحسابات المجانية و1,000 للقياسية والمؤسسية، وتستخدم الفئات
المفقودة أو غير المعروفة الحد المجاني.
- النص الفارغ أو المكوّن من مسافات فقط يصدر
VALIDATION_REQUIRED_FIELDغير قابل لإعادة المحاولة. - النص الذي لا يحتوي حرفًا ولا رقمًا، مثل علامات ترقيم فقط (
-أو...أو؟)، يصدرVALIDATION_INVALID_PARAMغير قابل لإعادة المحاولة. - النص الذي يتجاوز الحد الفعلي يصدر
CHARACTER_COUNT_EXCEEDEDغير قابل لإعادة المحاولة، ويحملdataمعboundبقيمةtts_input_charactersوunitبقيمةcharacters.
ويصل كل من VALIDATION_REQUIRED_FIELD وVALIDATION_INVALID_PARAM في حدث error يحمل
id الطلب. ويجري التحقق قبل التصنيع وقبل خصم دلو حد المعدل لكل مفتاح.
text نص UTF-8 عادي وليس SSML. تُزال وسوم الأداء مثل [happy] ولا تُحسب في
الحد؛ راجع المشاعر وأسلوب الإلقاء. أما أي ترميز آخر
فلا يحمل أي معنى: يُحسب في حد الأحرف كأي محارف أخرى، وقد يُنطَق اسم الوسم.
سياسة المحتوى
عندما يكون فرض سياسة المحتوى مفعّلًا، يصدر النص المرفوض
TTS_INPUT_NOT_ALLOWED غير القابل لإعادة المحاولة؛ غيّر النص قبل المحاولة
مجدّدًا. وإذا تعذر على جهة الإشراف على المحتوى اتخاذ قرار، يفشل التوليف بصورة
مغلقة مع TTS_MODERATION_UNAVAILABLE القابل لإعادة المحاولة. يفصل العقد بين
الحالتين حتى لا يظهر فشل البنية التحتية بوصفه محتوى محظورًا، وتصدر كلتاهما قبل
بدء التوليف.
حدود المرجع الصوتي
يقبل voice_references عنصرًا واحدًا بالضبط، ويُفحص كل حد عليه قبل البحث عن
النموذج وقبل حجز التزامن وقبل خصم حد المعدل، لذلك لا يستهلك الطلب المرفوض أي
حصة ولا أي خانة:
| الحالة | code | bound |
|---|---|---|
| أكثر من عنصر واحد | VOICE_REFERENCE_COUNT_EXCEEDED | tts_voice_reference_count |
| نص مرجع مفقود أو مكوّن من مسافات فقط | VALIDATION_REQUIRED_FIELD | — |
| نص مرجع لا يحتوي حرفًا ولا رقمًا | VALIDATION_INVALID_PARAM | — |
نص مرجع يتجاوز حده (الافتراضي 500 نقطة ترميز، مستقل عن ميزانية text ولا يستهلك منها) | CHARACTER_COUNT_EXCEEDED | tts_voice_reference_text_characters |
| صوت مرجعي يتجاوز سقف البايتات بعد فك الترميز (الافتراضي 2 MiB) | PAYLOAD_TOO_LARGE | tts_voice_reference_bytes |
| صوت مرجعي أطول من سقف المدة (الافتراضي 15 ثانية) | AUDIO_DURATION_EXCEEDED | tts_voice_reference_duration |
| مصفوفة فارغة صريحة | VALIDATION_INVALID_PARAM | — |
إرسال voice_id مع voice_references | VALIDATION_INVALID_PARAM | — |
| base64 غير قانوني بصرامة (فواصل أسطر، أو مسافات، أو أبجدية URL الآمنة، أو بتات حشو غير صفرية)، أو صوت ليس PCM16 أحادي القناة بصيغة RIFF/WAVE ببيانات غير فارغة | VALIDATION_INVALID_FORMAT | — |
ويُفحص سقف البايتات من طول base64 قبل فك ترميز الحمولة، لذلك لا يُنشأ المرجع المفرط في الحجم أبدًا. وسقف المدة مطابق لحد المرجع في النموذج المنشور نفسه، وتُحسب المدة من معدل العينات المعلن في الملف نفسه. والسقفان شاملان.
حذف الحقل، أو إرسال null، كلاهما يعني «لا مرجع»، ولذلك فإن voice_id مع
voice_references: null صالح ويستخدم voice_id. أما المصفوفة الفارغة الصريحة
[] فهي مصفوفة صحيحة التكوين تخالف minItems: 1 المعلن، ولذلك تُرفض.
ويمكن للنشر أن يخفض سقوف المرجع عبر
TTS_MAX_VOICE_REFERENCE_DECODED_BYTES وTTS_MAX_VOICE_REFERENCE_DURATION_SEC
وTTS_MAX_VOICE_REFERENCE_TEXT_CHARACTERS، لكنه لا يستطيع أبدًا رفعها فوق
الافتراضيات المنشورة.
أخطاء الرصيد والفوترة
يحجز كل طلب tts رصيدًا تحت id الخاص به قبل التوليف. ويصل الرفض في حدث error
يحمل id الطلب، ويبقى الاتصال مفتوحًا.
CREDITS_EXHAUSTED: نفد رصيد الحساب؛retryable: false.BILLING_AUTHORIZATION_UNAVAILABLE: تعذر على جهة اعتماد الفوترة اتخاذ قرار، فيفشل التوليف بصورة مغلقة؛retryable: true.BILLING_IDEMPOTENCY_CONFLICT: استُخدمidمن قبل لطلبttsبعدد أحرف مختلف؛retryable: false. وتفشل إعادة إرسالidنفسه بالطريقة نفسها، فأرسل UUID جديدًا لكل طلب.
تخطيط tts_audio
| الحقل | البايتات | القيمة والمعنى |
|---|---|---|
| UUID الطلب | 0–15 | معرّف الطلب نفسه في حمولة tts. |
| الرايات | 16 | bit 0 يحدد نهاية البث. |
| الصوت | 17–end | PCM16 little-endian، 24 kHz، أحادي القناة. |
socket.on("tts_audio", (buf: ArrayBuffer) => {
const bytes = Buffer.from(buf);
const isFinal = (bytes[16] & 0x01) === 1;
const audio = bytes.subarray(17);
});ناتج TTS هو موجة PCM خامة وليس WAV. أضف ترويسة WAV إذا أردت حفظ ملف قابل للتشغيل مباشرة.
قائمة الأصوات
socket.emit("tts_voice_list");
socket.on("tts_voice_list_result", (response) => {
for (const voice of response) {
console.log(voice.id, voice.label, voice.profile);
}
});تعيد القائمة هويات متعددة اللغات فقط؛ ولا تعرض معرّفات النسخ الفعلية أو
تقبلها في voice_id. يختار وجود أي حرف من محارف الكتابة العربية في text
النسخة العربية؛ وإلا تُختار الإنجليزية.
ويشرح قسم المشاعر وأسلوب الإلقاء الحقلين
profile.emotions وprofile.styles.
الأخطاء
قد تعاد أخطاء المصادقة، أو نموذج غير معروف، أو صوت غير صالح، أو ضغط السعة، أو
تجاوز أحد الحدود عبر حدث error. استخدم code أو error للتفرّع الآلي
وmessage للتشخيص.
عامل TTS_INPUT_NOT_ALLOWED بوصفه رفضًا غير قابل للإعادة للنص نفسه، وعامل
TTS_MODERATION_UNAVAILABLE بوصفه فشلًا عابرًا قابلًا للإعادة بعد تراجع محدود.
لا تستنتج من تعذر الإشراف أن النص خالف السياسة.
ويُحل voice_id المُرسَل قبل أي خصم حصة أو رسم حد معدل أو استدلال، وأخطاؤه
مُصنَّفة (SAU-2258): فـvoice_id الذي ليس UUID صالحًا يُصدر
VALIDATION_INVALID_UUID غير القابل لإعادة المحاولة؛ وvoice_id صالح البنية
لكنه لا يحدد صوتًا متاحًا يُصدر TTS_VOICE_NOT_FOUND غير القابل لإعادة المحاولة؛
وصوت محلول بياناته المخزَّنة ناقصة أو تالفة يُصدر TTS_VOICE_RESOLUTION_FAILED
غير القابل لإعادة المحاولة؛ وانقطاع عابر مصنَّف إيجابيًا لقاعدة البيانات/التخزين
أثناء الحل يُصدر SERVER_DEPENDENCY_FAILURE القابل لإعادة المحاولة. ولأن الحل
يسبق أي محاسبة، فإعادة محاولة الحالة القابلة لإعادة المحاولة آمنة.
ويحمل رفض الحدود كائن data يسمّي الحد وقيمته المضبوطة والقيمة المرصودة. أما
حالات الرفض القابلة لإعادة المحاولة فتحمل أيضًا retry_after_seconds، لأن هذا
النقل لا ترويسة Retry-After فيه:
{
"id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"code": "CONCURRENCY_LIMIT_EXCEEDED",
"message": "too many concurrent operations for this account",
"retryable": true,
"timestamp": "2026-01-15T10:30:00Z",
"retry_after_seconds": 5,
"data": {
"limit": 4,
"observed": 4,
"unit": "operations",
"bound": "account_concurrency_tts"
}
}حد العمليات المتزامنة لكل حساب قابل للفوترة، لذلك تتشارك عدة مفاتيح API تابعة لحساب واحد حصة واحدة. ولا يُغلق الاتصال: فالعمليات الأخرى المقبولة عليه تبقى تعمل.