أدلة APIمرجع أحداث Socket.IO

مرجع أحداث 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
أرسل id والنص والنموذج وإعدادات الصوت.
استقبال tts_audio
كل مقطع يحتوي UUID وراية النهاية وبايتات PCM16.
إلحاق الصوت
ألحق البايتات 17..end حتى تكون is_final مفعّلة.
طلب الأصوات
استخدم tts_voice_list لاكتشاف الأصوات المتاحة عند الحاجة.

الأحداث

الحدثالاتجاهالمعنى
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، ثم happy لجملة واحدة، ثم 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 عنصرًا واحدًا بالضبط، ويُفحص كل حد عليه قبل البحث عن النموذج وقبل حجز التزامن وقبل خصم حد المعدل، لذلك لا يستهلك الطلب المرفوض أي حصة ولا أي خانة:

الحالةcodebound
أكثر من عنصر واحدVOICE_REFERENCE_COUNT_EXCEEDEDtts_voice_reference_count
نص مرجع مفقود أو مكوّن من مسافات فقطVALIDATION_REQUIRED_FIELD—
نص مرجع لا يحتوي حرفًا ولا رقمًاVALIDATION_INVALID_PARAM—
نص مرجع يتجاوز حده (الافتراضي 500 نقطة ترميز، مستقل عن ميزانية text ولا يستهلك منها)CHARACTER_COUNT_EXCEEDEDtts_voice_reference_text_characters
صوت مرجعي يتجاوز سقف البايتات بعد فك الترميز (الافتراضي 2 MiB)PAYLOAD_TOO_LARGEtts_voice_reference_bytes
صوت مرجعي أطول من سقف المدة (الافتراضي 15 ثانية)AUDIO_DURATION_EXCEEDEDtts_voice_reference_duration
مصفوفة فارغة صريحةVALIDATION_INVALID_PARAM—
إرسال voice_id مع voice_referencesVALIDATION_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

tts_audio
الحقلالبايتاتالقيمة والمعنى
UUID الطلب0–15معرّف الطلب نفسه في حمولة tts.
الرايات16bit 0 يحدد نهاية البث.
الصوت17–endPCM16 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 تابعة لحساب واحد حصة واحدة. ولا يُغلق الاتصال: فالعمليات الأخرى المقبولة عليه تبقى تعمل.

في هذه الصفحة