مشاركة عبر

خصائص تركيب الدفعات للنص إلى كلام

  • مقالة

هام

واجهة برمجة تطبيقات تجميع الدفعات متاحة بشكل عام. سيتم إيقاف Long Audio API في 1 أبريل 2027. لمزيد من المعلومات، راجع الترحيل إلى واجهة برمجة تطبيقات تجميع الدفعات.

يمكن لواجهة برمجة تطبيقات تجميع الدفعات تركيب حجم كبير من إدخال النص (طويل وقصير) بشكل غير متزامن. يمكن للناشرين والأنظمة الأساسية لمحتوى الصوت إنشاء محتوى صوتي طويل على دفعة واحدة. على سبيل المثال: الكتب الصوتية والمقالات الإخبارية والوثائق. يمكن لواجهة برمجة تطبيقات تجميع الدفعات إنشاء صوت مركب أطول من 10 دقائق.

بعض الخصائص بتنسيق JSON مطلوبة عند إنشاء مهمة تجميع دفعة جديدة. الخصائص الأخرى اختيارية. تتضمن استجابة تجميع الدفعات خصائص أخرى لتوفير معلومات حول حالة التركيب والنتائج. على سبيل المثال، تحتوي الخاصية outputs.result على موقع ملفات نتائج تجميع الدفعات مع إخراج الصوت والسجلات.

خصائص تركيب الدفعات

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

الخاصية ‏‏الوصف
createdDateTime تاريخ ووقت إنشاء مهمة تجميع الدفعات.

هذه الخاصية للقراءة فقط.
customVoices خريطة اسم صوت مخصص ومعرف النشر الخاص به.

على سبيل المثال: "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}

يمكنك استخدام اسم الصوت في (عند inputKind تعيين إلى "PlainText") أو ضمن نص SSML ل inputs (عند inputKind تعيين إلى "SSML").synthesisConfig.voice

هذه الخاصية مطلوبة لاستخدام صوت مخصص. إذا حاولت استخدام صوت مخصص لم يتم تعريفه هنا، فترجع الخدمة خطأ.
description وصف تركيب الدفعة.

هذه الخاصية اختيارية.
id معرف مهمة تجميع الدفعات الذي مررته في المسار.

هذه الخاصية مطلوبة في المسار.
inputs النص العادي أو SSML المراد تركيبه.

inputKind عند تعيين إلى "PlainText"، قم بتوفير نص عادي كما هو موضح هنا: "inputs": [{"text": "The rainbow has seven colors."}]. inputKind عند تعيين إلى "SSML"، قم بتوفير نص بلغة ترميز تركيب الكلام (SSML) كما هو موضح هنا: "inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}].

قم بتضمين ما يصل إلى 1000 عنصر نصي إذا كنت تريد ملفات إخراج صوت متعددة. فيما يلي مثال على نص الإدخال الذي يجب تركيبه إلى ملفي إخراج صوتيين: "inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]. ومع ذلك، إذا تم تعيين الخاصية properties.concatenateResult إلى true، فستتم كتابة كل نتيجة تم تركيبها إلى نفس ملف إخراج الصوت.

لا تحتاج إلى إدخالات نص منفصلة للفقرات الجديدة. ضمن أي من إدخالات النص (حتى 1000)، يمكنك تحديد فقرات جديدة باستخدام السلسلة "\r\n" (سطر جديد). فيما يلي مثال على نص الإدخال مع فقرتين يجب تركيبهما إلى نفس ملف إخراج الصوت: "inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]

لا توجد حدود للفقرات، ولكن الحد الأقصى لحجم حمولة JSON (بما في ذلك جميع إدخالات النص والخصائص الأخرى) هو 2 ميغابايت.

هذه الخاصية مطلوبة عند إنشاء مهمة تجميع دفعة جديدة. لا يتم تضمين هذه الخاصية في الاستجابة عند الحصول على مهمة التركيب.
internalId معرف مهمة تركيب الدفعة الداخلية.

هذه الخاصية للقراءة فقط.
lastActionDateTime آخر تاريخ ووقت تغيرت فيه قيمة الخاصية status .

هذه الخاصية للقراءة فقط.
outputs.result موقع ملفات نتائج تجميع الدفعات مع إخراج الصوت والسجلات.

هذه الخاصية للقراءة فقط.
properties مجموعة محددة من إعدادات تكوين تجميع الدفعات الاختيارية.
properties.sizeInBytes حجم إخراج الصوت بالبايت.

هذه الخاصية للقراءة فقط.
properties.billingDetails عدد الكلمات التي تمت معالجتها والفوترة بواسطة customNeuralCharacters مقابل neuralCharacters الأصوات (التي تم إنشاؤها مسبقا).

هذه الخاصية للقراءة فقط.
properties.concatenateResult تحديد ما إذا كان يجب تسلسل النتيجة أم لا. هذه القيمة الاختيارية bool ("true" أو "false") هي "false" بشكل افتراضي.
properties.decompressOutputFiles تحديد ما إذا كان يجب فك ضغط ملفات نتائج التجميع في الحاوية الوجهة. يمكن تعيين هذه الخاصية فقط عند تعيين الخاصية destinationContainerUrl . هذه القيمة الاختيارية bool ("true" أو "false") هي "false" بشكل افتراضي.
properties.destinationContainerUrl يمكن تخزين نتائج تجميع الدفعات في حاوية Azure قابلة للكتابة. إذا لم تحدد حاوية URI مع رمز مميز لتوقيعات الوصول المشتركة (SAS)، فإن خدمة Speech تخزن النتائج في حاوية تديرها Microsoft. SAS مع نُهج الوصول المخزنة غير مدعوم. عند حذف مهمة التركيب، يتم حذف بيانات النتيجة أيضا.

لا يتم تضمين هذه الخاصية الاختيارية في الاستجابة عند الحصول على مهمة التركيب.
properties.destinationPath مسار البادئة حيث يمكن تخزين نتائج تجميع الدفعات معه. إذا لم تحدد مسار بادئة، فإن مسار البادئة الافتراضي هو YourSpeechResourceId/YourSynthesisId.

يمكن تعيين هذه الخاصية الاختيارية فقط عند تعيين الخاصية destinationContainerUrl .
properties.durationInMilliseconds مدة إخراج الصوت بالمللي ثانية.

هذه الخاصية للقراءة فقط.
properties.failedAudioCount فشل عدد مدخلات تركيب الدفعات لإخراج الصوت.

هذه الخاصية للقراءة فقط.
properties.outputFormat تنسيق إخراج الصوت.

للحصول على معلومات حول القيم المقبولة، راجع تنسيقات إخراج الصوت. تنسيق الإخراج الافتراضي هو riff-24khz-16bit-mono-pcm.
properties.sentenceBoundaryEnabled تحديد ما إذا كان يجب إنشاء بيانات حدود الجملة. هذه القيمة الاختيارية bool ("true" أو "false") هي "false" بشكل افتراضي.

إذا تم طلب بيانات حد الجملة، تضمين ملف مطابق [nnnn].sentence.json في ملف ZIP لبيانات النتائج.
properties.succeededAudioCount نجح عدد مدخلات تجميع الدفعات إلى إخراج الصوت.

هذه الخاصية للقراءة فقط.
properties.timeToLiveInHours مدة بالساعات بعد إنشاء مهمة التركيب، عندما سيتم حذف نتائج التركيب تلقائيا. هذا الإعداد الاختياري هو 744 (31 يوما) بشكل افتراضي. الحد الأقصى لفترة البقاء هو 31 يوما. تاريخ ووقت الحذف التلقائي (لمهام التركيب بحالة "ناجح" أو "فشل") يساوي الخصائص lastActionDateTime + timeToLiveInHours .

وإلا، يمكنك استدعاء أسلوب تجميع الحذف لإزالة المهمة في وقت أقرب.
properties.wordBoundaryEnabled تحديد ما إذا كان يجب إنشاء بيانات حدود الكلمات. هذه القيمة الاختيارية bool ("true" أو "false") هي "false" بشكل افتراضي.

إذا تم طلب بيانات حد كلمة، تضمين ملف مطابق [nnnn].word.json في ملف ZIP لبيانات النتائج.
status حالة معالجة تركيب الدفعة.

يجب أن تتقدم الحالة من "NotStarted" إلى "Running"، وأخيرا إلى "Succeeded" أو "Failed".

هذه الخاصية للقراءة فقط.
synthesisConfig إعدادات التكوين التي يجب استخدامها لتركيب دفعة من النص العادي.

هذه الخاصية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.backgroundAudio الصوت في الخلفية لكل إخراج صوت.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.backgroundAudio.fadein مدة تلاشي الصوت في الخلفية بالمللي ثانية. القيمة الافتراضية هي 0، وهي تكافئ عدم الزيادة التدريجية للصوت. القيم المقبولة: 0 إلى 10000 شاملة.

للحصول على معلومات، راجع جدول السمات ضمن إضافة صوت الخلفية في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.backgroundAudio.fadeout مدة تلاشي الصوت في الخلفية بالمللي ثانية. القيمة الافتراضية هي 0، وهي ما يعادل عدم التلاشي. القيم المقبولة: 0 إلى 10000 شاملة.

للحصول على معلومات، راجع جدول السمات ضمن إضافة صوت الخلفية في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.backgroundAudio.src موقع URI لملف الصوت في الخلفية.

للحصول على معلومات، راجع جدول السمات ضمن إضافة صوت الخلفية في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية مطلوبة عند synthesisConfig.backgroundAudio تعيينها.
synthesisConfig.backgroundAudio.volume مستوى صوت ملف الصوت في الخلفية. القيم المقبولة: 0 إلى 100 شاملة. القيمة الافتراضية هي 1.

للحصول على معلومات، راجع جدول السمات ضمن إضافة صوت الخلفية في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.pitch درجة إخراج الصوت.

للحصول على معلومات حول القيم المقبولة، راجع جدول ضبط prosody في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.rate معدل إخراج الصوت.

للحصول على معلومات حول القيم المقبولة، راجع جدول ضبط prosody في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.role بالنسبة لبعض الأصوات، يمكنك ضبط لعب الأدوار المتحدثة. يمكن أن يقلد الصوت عمرا وجنسا مختلفين، ولكن اسم الصوت لا يتغير. على سبيل المثال، يمكن للصوت الذكوري رفع درجة الصوت وتغيير الرجم لتقليد صوت أنثى، ولكن لا يتغير اسم الصوت. إذا كان الدور مفقودا أو غير مدعوم لصوتك، يتم تجاهل هذه السمة.

للحصول على معلومات حول الأنماط المتوفرة لكل صوت، راجع أنماط الصوت وأدواره.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.speakerProfileId معرف ملف تعريف المتحدث لصوت شخصي.

للحصول على معلومات حول أسماء نماذج قاعدة الصوت الشخصية المتوفرة، راجع دمج الصوت الشخصي.
للحصول على معلومات حول كيفية الحصول على معرف ملف تعريف المتحدث، راجع دعم اللغة والصوت.

هذه الخاصية مطلوبة عند inputKind تعيين إلى "PlainText".
synthesisConfig.style بالنسبة لبعض الأصوات، يمكنك ضبط أسلوب التحدث للتعبير عن عواطف مختلفة مثل البهجة والتعاطف والهدوء. يمكنك تحسين الصوت لسيناريوهات مختلفة مثل خدمة العملاء ونشرة الأخبار والمساعد الصوتي.

للحصول على معلومات حول الأنماط المتوفرة لكل صوت، راجع أنماط الصوت وأدواره.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند synthesisConfig.style تعيينها.
synthesisConfig.styleDegree شدة أسلوب التحدث. يمكنك تحديد نمط أقوى أو أكثر ليونة لجعل الكلام أكثر تعبيرا أو منخفضا. نطاق القيم المقبولة هو: 0.01 إلى 2 ضمنا. القيمة الافتراضية هي 1، وهي تشير إلى شدة النمط المعرّفة مسبقاً. أدنى وحدة هي 0.01، وهي تؤدي إلى تحوّل بسيط للنمط المستهدف. تؤدي القيمة 2 إلى مضاعفة شدة النمط الافتراضي. إذا كانت درجة النمط مفقودة أو غير معتمدة لصوتك، يتم تجاهل هذه السمة.

للحصول على معلومات حول الأنماط المتوفرة لكل صوت، راجع أنماط الصوت وأدواره.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
synthesisConfig.voice الصوت الذي يتحدث إخراج الصوت.

للحصول على معلومات حول الأصوات العصبية المتوفرة التي تم إنشاؤها مسبقا، راجع دعم اللغة والصوت. لاستخدام صوت مخصص، يجب تحديد تعيين صحيح مخصص للصوت ومعرف النشر في الخاصية customVoices . لاستخدام صوت شخصي، تحتاج إلى تحديد الخاصية synthesisConfig.speakerProfileId .

هذه الخاصية مطلوبة عند inputKind تعيين إلى "PlainText".
synthesisConfig.volume حجم إخراج الصوت.

للحصول على معلومات حول القيم المقبولة، راجع جدول ضبط prosody في وثائق Speech Synthesis Markup Language (SSML). يتم تجاهل القيم غير الصالحة.

هذه الخاصية الاختيارية قابلة للتطبيق فقط عند inputKind تعيين إلى "PlainText".
inputKind يشير إلى ما إذا كان inputs يجب أن تكون خاصية النص نصا عاديا أو SSML. القيم المحتملة غير الحساسة لحالة الأحرف هي "نص عادي" و"SSML". inputKind عند تعيين إلى "PlainText"، يجب عليك أيضا تعيين synthesisConfig خاصية الصوت.

هذه الخاصية مطلوبة.

زمن انتقال تركيب الدفعات وأفضل الممارسات

عند استخدام تركيب الدفعة لتوليد الكلام المركب، من المهم مراعاة زمن الانتقال المضمن واتباع أفضل الممارسات لتحقيق النتائج المثلى.

زمن الانتقال في تركيب الدفعة

يعتمد زمن الانتقال في تركيب الدفعة على عوامل مختلفة، بما في ذلك تعقيد نص الإدخال، وعدد المدخلات في الدفعة، وقدرات المعالجة للأجهزة الأساسية.

زمن الانتقال لتركيب الدفعات كما يلي (تقريبا):

  • زمن انتقال 50٪ من مخرجات الكلام المركب في غضون 10-20 ثانية.

  • زمن انتقال 95٪ من مخرجات الكلام المركب في غضون 120 ثانية.

أفضل الممارسات

عند النظر في تركيب الدفعات للتطبيق الخاص بك، يوصى بتقييم ما إذا كان زمن الانتقال يفي بمتطلباتك. إذا كان زمن الانتقال يتوافق مع الأداء المطلوب، يمكن أن يكون تركيب الدفعة خيارا مناسبا. ومع ذلك، إذا كان زمن الانتقال لا يلبي احتياجاتك، فقد تفكر في استخدام واجهة برمجة التطبيقات في الوقت الحقيقي.

تعليمة برمجية حالة HTTP

يفصل القسم رموز استجابة HTTP والرسائل من واجهة برمجة تطبيقات تجميع الدفعات.

HTTP 200 OK

يشير HTTP 200 OK إلى نجاح الطلب.

تم إنشاء HTTP 201

يشير HTTP 201 Created إلى نجاح طلب إنشاء تركيب دفعة (عبر HTTP POST).

خطأ HTTP 204

يشير خطأ HTTP 204 إلى نجاح الطلب، ولكن المورد غير موجود. على سبيل المثال:

  • لقد حاولت الحصول على مهمة تركيب غير موجودة أو حذفها.
  • لقد حذفت وظيفة تركيب بنجاح.

خطأ HTTP 400

فيما يلي أمثلة يمكن أن تؤدي إلى الخطأ 400:

  • outputFormat غير معتمد أو غير صالح. قم بتوفير قيمة تنسيق صالحة، أو اتركها outputFormat فارغة لاستخدام الإعداد الافتراضي.
  • تجاوز عدد إدخالات النص المطلوبة الحد الأقصى وهو 10,000.
  • لقد حاولت استخدام معرف نشر غير صالح أو صوت مخصص لم يتم نشره بنجاح. تأكد من أن مورد الكلام لديه حق الوصول إلى الصوت المخصص، ومن نشر الصوت المخصص بنجاح. يجب عليك أيضا التأكد من {"your-custom-voice-name": "your-deployment-ID"} أن تعيين صحيح في طلب تركيب الدفعة.
  • لقد حاولت استخدام مورد الكلام F0 ، ولكن المنطقة تدعم فقط مستوى تسعير مورد الكلام القياسي .

خطأ HTTP 404

لا يمكن العثور على الكيان المحدد. تأكد من صحة معرف التوليف.

خطأ HTTP 429

هناك عدد كبير جدا من الطلبات الأخيرة. يمكن لكل تطبيق عميل إرسال ما يصل إلى 100 طلب لكل 10 ثوان لكل مورد Speech. تقليل عدد الطلبات في الثانية.

خطأ HTTP 500

يشير خطأ خادم HTTP 500 الداخلي إلى فشل الطلب. يحتوي نص الاستجابة على رسالة الخطأ.

مثال على خطأ HTTP

فيما يلي مثال على طلب ينتج خطأ HTTP 400، لأن الخاصية inputs مطلوبة لإنشاء وظيفة.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML"
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

في هذه الحالة، تتضمن HTTP/1.1 400 Bad Requestرؤوس الاستجابة .

يشبه نص الاستجابة مثال JSON التالي:

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

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