التقاط تدفق إطارات خدمة TTS عبر HTTP
أرسل نصًا واحفظ تسجيل بروتوكول ثنائي بلا فواصل بتردد 16 kHz؛ الاستجابة ليست PCM أو WAV قابلاً للتشغيل.
/http/ttsهذه عملية مباشرة عبر HTTP للمنصة. تستخدم حزم SDK لـJavaScript وPython في
الإصدار 0.18.0 بروتوكول Socket.IO ولا تستدعي هذا المسار. أرسل الطلب من
خلفية موثوقة مع X-Api-Key وقدرة TTS.
أرسل UUID جديدًا في id، ونصًا في text على المستوى الأعلى يحتوي على حرف Unicode واحد أو رقم واحد على الأقل بعد إزالة الفراغات الطرفية، ومفتاح النموذج الصريح nebula.
لاختيار صوت متوقع، أرسل إما voice_id واحدًا بالضبط أو عنصرًا واحدًا في
voice_references، ولا تجمع بينهما. احصل على voice_id عبر listVoices()
أو list_voices() في SDK؛ فلا توجد عملية HTTP لسرد الأصوات. يعرّف UUID المعاد واحدة من هويات
الأصوات السبع متعددة اللغات. نسخها الفعلية داخلية، ويُرفض الاستخدام المباشر
لـUUID أي نسخة فعلية. إذا حُذف
model، يستخدم النشر مفتاح النموذج الافتراضي المضبوط لديه، مع الرجوع إلى
nebula. وإذا حُذف محدد الصوت، يعتمد اختيار الصوت على النشر.
تحسب الخدمة نقاط ترميز Unicode، لا بايتات UTF-8 ولا عناقيد الرسوم المعروضة.
وتُحفظ الفراغات في البداية والنهاية وتُحسب ضمن الحد. الحدود الافتراضية شاملةً
هي 500 نقطة ترميز للحسابات المجانية و1000 للحسابات القياسية وحسابات
المؤسسات. وتستخدم الفئات المفقودة أو غير المعروفة الحد المجاني. ويمكن لعمليات
النشر تجاوز هذه الحدود بصورة مستقلة عبر TTS_MAX_INPUT_CHARACTERS_FREE
وTTS_MAX_INPUT_CHARACTERS_STANDARD وTTS_MAX_INPUT_CHARACTERS_ENTERPRISE،
لذلك لا يعلن هذا المخطط قيمة maxLength ثابتة عمدًا.
يجب أن يكون audio المرجعي RIFF/WAVE بترميز base64 القياسي، وأن يحتوي
صوت PCM16 أحادي القناة غير فارغ، وأن يرافقه نصه.
جسم استجابة HTTP 200 تسلسل بلا فواصل من إطارات الخدمة: 16 بايتًا
خامًا لـUUID، ثم بايت علم النهاية، ثم بايتات PCM16 بترتيب little-endian وتردد
16 kHz. لا تحافظ حدود القراءة العادية عبر HTTP على حدود إطارات الخدمة؛ لذلك
لا يمكن فك هذا الجسم عمومًا بوصفه PCM خامًا أو WAV. احفظه فقط كتسجيل بروتوكول.
استخدم TTS عبر Socket.IO ووصفة TTS-to-WAV للحصول على خرج قابل للتشغيل.
طبّق مهلًا نهائية محدودة للاتصال وعدم النشاط أو القراءة والعملية كاملة. لا
يعني EOF أو الإلغاء من دون علم نهاية معروف الحدود اكتمالًا. ويلغي إجهاض طلب
HTTP التصنيع الجاري له وحده. وينهي الفشل بعد إرسال البايتات البثَّ الثنائي
الجزئي؛ ولا تلحق الخدمة أبدًا مستند JSON للخطأ بجسم 200 الثنائي. افصل
البايتات الجزئية عن الخرج المكتمل. لا تدعم هذه العملية عقد idempotency؛
استخدم UUID جديدًا لإعادة محاولة يوافق عليها التطبيق.
المصادقة
ApiKeyAuth الموضع: header
جسم الطلب
application/json
تعريفات TypeScript
استخدم هذا النوع في TypeScript.
جسم الاستجابة
application/octet-stream
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -sS --fail-with-body --connect-timeout 10 --max-time 120 -X POST \ "https://example.com/http/tts" \ -H "Origin: https://example.com" \ -H "Content-Type: application/json" \ --data '{ "id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8", "text": "Hello from HUMAIN Voice", "model": "nebula"}'تسلسل بلا فواصل من إطارات خدمة TTS، وليس PCM خامًا ولا WAV. ليست مقاطع القراءة العادية عبر HTTP حدودًا لإطارات الخدمة. وحده عميل يملك آلية تأطير خاصة بالبيئة يستطيع تحديد علم النهاية؛ ولا يثبت EOF وحده الاكتمال.
application/octet-stream
إدخال مشوّه، بما في ذلك id طلب غير قابل للتحليل، أو نص أو مرجع صوتي
مفقود أو غير قابل للاستخدام. وهذه حالات فشل تحقق غير قابلة لإعادة المحاولة وتحدث
قبل أن يبدأ التصنيع.
ويُبلَّغ أيضًا عن النص الصالح الذي ترفضه سياسة محتوى TTS بالرمز
TTS_INPUT_NOT_ALLOWED. وهو غير قابل لإعادة المحاولة: فلن يُقبل النص نفسه،
ولذلك غيّر النص قبل إرسال طلب آخر.
ويُبلَّغ عن id الطلب المشوّه بالرمز VALIDATION_INVALID_FORMAT، مع كل حالات
فشل الجسم المشوّه الأخرى: فـid يُحلَّل أثناء فك ترميز JSON، ولذلك تُفشل القيمة
غير القابلة للتحليل الجسم كله بدلًا من أن تصل إلى فحص مخصص. وid الطلب نفسه لا
ينتج عنه أبدًا VALIDATION_INVALID_UUID على هذا المسار.
أما voice_id المُرسَل من العميل فيُبلَّغ عنه هنا (SAU-2258): فـvoice_id الذي
ليس UUID صالحًا هو VALIDATION_INVALID_UUID، وvoice_id صالح البنية لكنه لا
يحدد صوتًا متاحًا هو TTS_VOICE_NOT_FOUND. وكلاهما 400 وغير قابل لإعادة
المحاولة — فإعادة إرسال voice_id نفسه لا يمكن أن تنجح؛ صحّحه أو أرسل
voice_references بدلًا منه. (أما بيانات الصوت الموجودة لكن الناقصة أو التالفة،
أو انقطاع تخزين/قاعدة بيانات مثبت، فهي حالات من جهة الخادم يُبلَّغ عنها بالحالة
500/503 — راجع استجابتَي 500 و503.)
وتجاوزات النص والمرجع ليست هنا: فتجاوز حد أحرف الفئة أو حد نص المرجع أو عدد
المراجع هو الحالة 422، والمرجع الذي يزيد حجمه بعد فك الترميز هو الحالة 413.
application/json
المثال invalid_body
{
"error": "Invalid request body",
"code": "VALIDATION_INVALID_FORMAT",
"detail": "Invalid request body",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}`id` الطلب ليس UUID صالحًا، فيفشل فك ترميز الجسم
{
"error": "Invalid request body",
"code": "VALIDATION_INVALID_FORMAT",
"detail": "Invalid request body",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}النص فارغ أو يحتوي على فراغات Unicode فقط
{
"error": "TTS input must contain non-whitespace text",
"code": "VALIDATION_REQUIRED_FIELD",
"detail": "TTS input must contain non-whitespace text",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}أُرسل voice_id وvoice_references معًا
{
"error": "voice_id and voice_references are mutually exclusive",
"code": "VALIDATION_INVALID_PARAM",
"detail": "voice_id and voice_references are mutually exclusive",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}مصفوفة فارغة صريحة؛ احذف الخاصية بدلًا من ذلك
{
"error": "voice_references must contain exactly one reference when present; omit the field to use the default voice",
"code": "VALIDATION_INVALID_PARAM",
"detail": "voice_references must contain exactly one reference when present; omit the field to use the default voice",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}الصوت المرجعي ليس RIFF/WAVE بترميز base64 قانوني وPCM16 أحادي القناة
{
"error": "voice_references[0].audio is not valid reference audio: audio must be a RIFF/WAVE file",
"code": "VALIDATION_INVALID_FORMAT",
"detail": "voice_references[0].audio is not valid reference audio: audio must be a RIFF/WAVE file",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}نص المرجع مفقود أو مكوّن من مسافات فقط
{
"error": "voice_references[0].text must contain the reference transcript",
"code": "VALIDATION_REQUIRED_FIELD",
"detail": "voice_references[0].text must contain the reference transcript",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}voice_id موجود لكنه ليس UUID صالحًا
{
"error": "voice_id must be a valid UUID",
"code": "VALIDATION_INVALID_UUID",
"detail": "voice_id must be a valid UUID",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}voice_id صالح البنية (UUID) لكنه لا يحدد صوتًا متاحًا
{
"error": "voice_id does not identify an available voice",
"code": "TTS_VOICE_NOT_FOUND",
"detail": "voice_id does not identify an available voice",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}نص رفضته سياسة محتوى TTS
{
"error": "TTS input is not allowed",
"code": "TTS_INPUT_NOT_ALLOWED",
"detail": "TTS input is not allowed",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}غير مصرح
application/json
المثال missing_key
{
"error": "Invalid authentication",
"code": "AUTH_UNAUTHORIZED",
"detail": "Invalid authentication",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}لا يمنح مفتاح API صلاحية الوصول إلى قدرة الصوت المطلوبة
application/json
المثال scope_denied
{
"error": "scope not permitted",
"code": "AUTH_FORBIDDEN",
"detail": "scope not permitted",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}الطريقة غير مسموحة
application/json
المثال wrong_method
{
"error": "method not allowed",
"code": "METHOD_NOT_ALLOWED",
"detail": "method not allowed",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}تجاوز جسم الطلب الحد المضبوط لهذا المسار (16 MiB لأجسام طلبات TTS). وهذا الفشل غير قابل لإعادة المحاولة بالحجم نفسه؛ أرسل طلبًا أصغر.
ولا تحمل صورة جسم الطلب من هذه الاستجابة أي كائن data. أما المسارات الصوتية
الثلاثة فتجيب على الجسم المفرط في الحجم بالحالة والرمز نفسيهما لكنها تتضمن
data؛ راجع توثيق 413 الخاص بها.
كما يجيب POST /http/tts بهذه الحالة عندما يتجاوز الصوت المرجعي بعد فك الترميز
سقف البايتات لكل مرجع في النشر (الافتراضي 2 MiB)، وتلك الصورة تحمل data مع
bound بقيمة tts_voice_reference_bytes وunit بقيمة bytes. ويُفحص ذلك من
طول base64 قبل فك ترميز الحمولة، لذلك لا يُنشأ المرجع المفرط في الحجم أبدًا.
application/json
المثال body_too_large
{
"error": "request body too large",
"code": "PAYLOAD_TOO_LARGE",
"detail": "request body too large",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}الصوت المرجعي بعد فك الترميز يتجاوز سقف البايتات لكل مرجع
{
"error": "voice_references[0].audio decodes to 3145728 bytes; limit is 2097152",
"code": "PAYLOAD_TOO_LARGE",
"detail": "voice_references[0].audio decodes to 3145728 bytes; limit is 2097152",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"limit": 2097152,
"observed": 3145728,
"unit": "bytes",
"bound": "tts_voice_reference_bytes"
}
}حُلِّل الطلب بصورة صحيحة وكل حقل فيه صالح على حدة، لكن وحدة عمل دلالية
تتجاوز سقفها (RFC 9110 15.5.21). فبضع مئات من البايتات من النص قد تطلب عمل
تصنيع أكبر بكثير مما يشير إليه حجمها، ولذلك لا يمكن التعبير عن هذه الحدود بسقف
بايتات ولا تكون أبدًا الحالة 413.
ويسمّي data.bound السقف الذي تم بلوغه:
tts_input_characters—textأطول من حد أحرف فئة الحساب (الافتراضيات: 500 للمجاني، و1,000 للقياسي والمؤسسي).tts_voice_reference_text_characters—voice_references[0].textأطول من حد نص المرجع (الافتراضي 500).tts_voice_reference_count— أكثر من عنصر واحد فيvoice_references؛ وmaxItemsالمنشور هو 1.tts_voice_reference_duration— الصوت المرجعي بعد فك الترميز أطول من سقف النشر (الافتراضي 15 ثانية)، وهو مطابق لحد المرجع في النموذج المنشور نفسه. وdata.observedبالثواني الكاملة، مقرَّبًا إلى الأعلى.
وكل واحد من هذه يُفحص قبل أي بحث عن نموذج أو قبول أو محاسبة، لذلك لا يستهلك الطلب المرفوض أي حصة ولا أي خانة تزامن. وهو غير قابل لإعادة المحاولة: فإعادة إرسال الطلب نفسه لا يمكن أن تنجح.
application/json
النص يتجاوز الحد الافتراضي للفئة المجانية في وقت التشغيل
{
"error": "TTS input contains 501 characters; limit is 500",
"code": "CHARACTER_COUNT_EXCEEDED",
"detail": "TTS input contains 501 characters; limit is 500",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"limit": 500,
"observed": 501,
"unit": "characters",
"bound": "tts_input_characters"
}
}نص المرجع يتجاوز حده المستقل الخاص
{
"error": "voice_references[0].text contains 501 characters; limit is 500",
"code": "CHARACTER_COUNT_EXCEEDED",
"detail": "voice_references[0].text contains 501 characters; limit is 500",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"limit": 500,
"observed": 501,
"unit": "characters",
"bound": "tts_voice_reference_text_characters"
}
}أكثر من maxItems المنشور وقيمته 1
{
"error": "voice_references contains 2 references; limit is 1",
"code": "VOICE_REFERENCE_COUNT_EXCEEDED",
"detail": "voice_references contains 2 references; limit is 1",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"limit": 1,
"observed": 2,
"unit": "references",
"bound": "tts_voice_reference_count"
}
}مقطع مرجعي أطول من حد المرجع في النموذج المنشور
{
"error": "voice_references[0].audio is 16 seconds long; limit is 15",
"code": "AUDIO_DURATION_EXCEEDED",
"detail": "voice_references[0].audio is 16 seconds long; limit is 15",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"limit": 15,
"observed": 16,
"unit": "seconds",
"bound": "tts_voice_reference_duration"
}
}لدى الحساب فعلًا من العمليات المتزامنة من هذا النوع قيد التنفيذ ما تسمح به خطته، محسوبة عبر كل نسخة من الخادم (SAU-2181). والحد لكل حساب قابل للفوترة، لذلك تتشارك عدة مفاتيح API تابعة لحساب واحد حصة واحدة، وإنشاء مفاتيح أكثر لا يرفعها. ولكل نوع عمل حصته الخاصة، لذلك لا يتنافس ASR الفوري وTTS أحدهما مع الآخر.
وهذه الحالة قابلة لإعادة المحاولة وتزول عادة في ثوان، بمجرد انتهاء إحدى عمليات
الحساب الجارية. التزم بترويسة Retry-After.
ولا تخلط بينها وبين الحالة 429 الأخرى على هذه المسارات: فحد معدل الطلبات لكل
مفتاح في البوابة يبلّغ RATE_LIMIT_EXCEEDED، وسقف جلسات HTTP لكل اتصال يبلّغ
SESSION_SLOTS_EXHAUSTED. ويميز بينها حقل code. ولا يستهلك الرفض أي رصيد
ولا أي حصة.
application/json
المثال account_concurrency_exhausted
{
"error": "too many concurrent operations for this account",
"code": "CONCURRENCY_LIMIT_EXCEEDED",
"detail": "too many concurrent operations for this account",
"retryable": true,
"timestamp": "2026-01-15T10:30:00Z",
"data": {
"limit": 4,
"observed": 4,
"unit": "operations",
"bound": "account_concurrency_tts"
}
}فشل TTS قبل تثبيت الخرج الثنائي. وإذا كان الخرج قد ثُبِّت فعلًا، ينتهي بث 200
الثنائي الجزئي من دون إلحاق خطأ JSON.
وتحمل هذه الحالة رمزين متمايزين. TTS_SYNTHESIS_FAILED هو الحالة القابلة لإعادة
المحاولة: فشل في حل النموذج أو السعة أو الاستدلال قد تزيله محاولة لاحقة.
وTTS_VOICE_RESOLUTION_FAILED (SAU-2258) غير قابل لإعادة المحاولة: صوت محلول
بياناته المخزَّنة ناقصة أو تالفة (صوت أو نص مفقود، أو URI مخزَّن غير قابل
للاستخدام، أو صوت ليس PCM بترميز INT16)، أو خطأ قاعدة بيانات/تخزين غير مصنَّف.
وإعادة إرسال الطلب نفسه لا يمكن أن تصلح بيانات صوت معطوبة من جهة الخادم.
ولا تصل إلى هنا حالات فشل التحقق من النص ومن المرجع الصوتي: فهي تُبلَّغ بالحالة
400 أو 413 أو 422 برمز محدد قبل أن يبدأ التصنيع. كما أن voice_id
المُرسَل من العميل إذا كان غير صالح أو غير معروف فليس هنا أيضًا — بل هو 400
(VALIDATION_INVALID_UUID / TTS_VOICE_NOT_FOUND)؛ وانقطاع قاعدة بيانات/تخزين
مثبت أثناء حل الصوت هو 503 (SERVER_DEPENDENCY_FAILURE، قابل لإعادة المحاولة).
application/json
فشل نموذج/سعة/استدلال قابل لإعادة المحاولة
{
"error": "TTS synthesis failed",
"code": "TTS_SYNTHESIS_FAILED",
"detail": "TTS synthesis failed",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": true,
"timestamp": "2026-01-15T10:30:00Z"
}الصوت المحلول بياناته المخزَّنة ناقصة أو تالفة (غير قابل لإعادة المحاولة)
{
"error": "selected voice could not be resolved",
"code": "TTS_VOICE_RESOLUTION_FAILED",
"detail": "selected voice could not be resolved",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": false,
"timestamp": "2026-01-15T10:30:00Z"
}إحدى التبعيات المطلوبة غير متاحة مؤقتًا. والاستجابة قابلة لإعادة المحاولة: فقد ينجح الطلب نفسه بعد تعافي تلك التبعية.
تعني TTS_MODERATION_UNAVAILABLE أن جهة الإشراف على المحتوى لم تتمكن من اتخاذ
قرار، ولذلك فشل التوليف بصورة مغلقة. وهي متمايزة عمدًا عن
TTS_INPUT_NOT_ALLOWED: فلا ينبغي الإبلاغ عن فشل البنية التحتية بوصفه رفضًا
للسياسة.
تمثل SERVER_DEPENDENCY_FAILURE انقطاعًا عابرًا مصنَّفًا إيجابيًا لقاعدة
بيانات أو تخزين كائنات أثناء حل voice_id (SAU-2258). وهي متمايزة عن
500 TTS_VOICE_RESOLUTION_FAILED، التي تحدد بيانات صوت معطوبة من جهة الخادم
لا تصلحها إعادة المحاولة. ويجري الفحصان قبل أي خصم حصة أو رسم حد معدل أو
استدلال، ولذلك لا يُحاسب الطلب المُعاد مرتين.
application/json
انقطاع عابر لقاعدة البيانات/التخزين أثناء حل الصوت
{
"error": "voice resolution is temporarily unavailable",
"code": "SERVER_DEPENDENCY_FAILURE",
"detail": "voice resolution is temporarily unavailable",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": true,
"timestamp": "2026-01-15T10:30:00Z"
}جهة الإشراف على المحتوى غير متاحة مؤقتًا
{
"error": "TTS moderation is unavailable",
"code": "TTS_MODERATION_UNAVAILABLE",
"detail": "TTS moderation is unavailable",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": true,
"timestamp": "2026-01-15T10:30:00Z"
}انقضت مهلة التصنيع غير القابلة لإعادة الضبط والبالغة 25 ثانية قبل توفر نتيجة نهائية كاملة على مستوى البروتوكول. هذه الاستجابة قابلة لإعادة المحاولة ولا تُعاد إلا عندما لا يكون الخرج الثنائي قد بدأ؛ وإلا فينتهي البث الثنائي الجزئي من دون إلحاق JSON.
application/json
المثال deadline_exceeded
{
"error": "TTS synthesis deadline exceeded",
"code": "TTS_DEADLINE_EXCEEDED",
"detail": "TTS synthesis deadline exceeded",
"job_id": "7f51f2c2-e7bc-41c8-a850-f848df2ddfc8",
"retryable": true,
"timestamp": "2026-01-15T10:30:00Z"
}الخطوات التالية
استجابة HTTP المباشرة تسجيل بروتوكول بلا فواصل، وليست PCM خامًا قابلاً للاستعادة ولا WAV. لا تضف إليها ترويسة WAV. للخرج القابل للتشغيل، استخدم مسار SDK المنشورة عبر Socket.IO، ولا تضف ترويسة WAV إلا بعد جمع حمولة PCM النهائية التي فكها SDK.