مرجع أحداث TTS

يستقبل 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

{
  "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 لتكييف الصوت من مراجع صوتية.

حدود النص

يُحسب طول text بنقاط ترميز Unicode، لا ببايتات UTF-8 ولا بعناقيد المحارف المعروضة؛ وتُحفظ المسافات في البداية والنهاية وتُحسب. والافتراضيات الشاملة هي 500 نقطة ترميز للحسابات المجانية و1,000 للقياسية والمؤسسية، وتستخدم الفئات المفقودة أو غير المعروفة الحد المجاني.

• النص الفارغ أو المكوّن من مسافات فقط يصدر VALIDATION_REQUIRED_FIELD غير قابل لإعادة المحاولة.
• النص الذي لا يحتوي حرفًا ولا رقمًا، مثل علامات ترقيم فقط، يصدر VALIDATION_INVALID_PARAM غير قابل لإعادة المحاولة.
• النص الذي يتجاوز الحد الفعلي يصدر CHARACTER_COUNT_EXCEEDED غير قابل لإعادة المحاولة، ويحمل data مع bound بقيمة tts_input_characters.

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

سياسة المحتوى

عندما يكون فرض سياسة المحتوى مفعّلًا، يصدر النص المرفوض TTS_INPUT_NOT_ALLOWED غير القابل لإعادة المحاولة؛ غيّر النص قبل المحاولة مجدّدًا. وإذا تعذر على جهة الإشراف على المحتوى اتخاذ قرار، يفشل التوليف بصورة مغلقة مع TTS_MODERATION_UNAVAILABLE القابل لإعادة المحاولة. يفصل العقد بين الحالتين حتى لا يظهر فشل البنية التحتية بوصفه محتوى محظورًا، وتصدر كلتاهما قبل بدء التوليف.

حدود المرجع الصوتي

يقبل voice_references عنصرًا واحدًا بالضبط، ويُفحص كل حد عليه قبل البحث عن النموذج وقبل حجز التزامن وقبل خصم حد المعدل، لذلك لا يستهلك الطلب المرفوض أي حصة ولا أي خانة:

ويُفحص سقف البايتات من طول 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_audio

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 النسخة العربية؛ وإلا تُختار الإنجليزية.

الأخطاء

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