واجهة برمجة تطبيقات تجميع الدفعات للنص إلى كلام

مقالة
05/30/2024

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

هام

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

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

يوفر هذا الرسم التخطيطي نظرة عامة عالية المستوى على سير العمل.

رسم تخطيطي لسير عمل Batch Synthesis API.

تلميح

يمكنك أيضا استخدام Speech SDK لإنشاء صوت مركب أطول من 10 دقائق عن طريق التكرار عبر النص وتجميعه في مجموعات. للحصول على مثال C#، راجع GitHub.

يمكنك استخدام عمليات REST API التالية لتجميع الدفعات:

العملية	الأسلوب	استدعاء واجهة برمجة تطبيقات REST
إنشاء تركيب دفعي	`PUT`	texttospeech/batchsyntheses/YourSynthesisId
الحصول على تركيب الدفعة	`GET`	texttospeech/batchsyntheses/YourSynthesisId
تركيب دفعة القائمة	`GET`	texttospeech/batchsyntheses
حذف تركيب الدفعة	`DELETE`	texttospeech/batchsyntheses/YourSynthesisId

للحصول على نماذج التعليمات البرمجية، راجع GitHub.

إنشاء تركيب دفعي

لإرسال طلب تجميع دفعي، قم بإنشاء مسار طلب HTTP PUT والنص وفقا للإرشادات التالية:

عيّن الخاصية inputKind المطلوبة.
إذا تم تعيين الخاصية inputKind إلى "نص عادي"، فيجب عليك أيضا تعيين الخاصية voice في synthesisConfig. في المثال أدناه، inputKind يتم تعيين إلى "SSML"، لذلك synthesisConfig لم يتم تعيين .
اختياريا يمكنك تعيين descriptiontimeToLiveInHoursالخصائص و و و الأخرى. لمزيد من المعلومات، راجع خصائص تركيب الدفعات.

إشعار

الحد الأقصى لحجم حمولة JSON التي سيتم قبولها هو 2 ميغابايت.

تعيين المطلوب YourSynthesisId في المسار. يجب YourSynthesisId أن يكون فريدا. يجب أن يكون طوله من 3 إلى 64، ويحتوي فقط على أرقام وأحرف وواصلات وتسطير أسفل السطر والنقاط، ويبدأ وينتهي بحرف أو رقم.

قم بإجراء طلب HTTP PUT باستخدام URI كما هو موضح في المثال التالي. استبدل YourSpeechKey بمفتاح مورد الكلام لديك، واستبدل YourSpeechRegion بمنطقة مورد الكلام، وعيّن خصائص نص الطلب كما هو موضح سابقاً.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

يجب أن تتلقى نص الاستجابة بالتنسيق التالي:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false
  }
}

status يجب أن تتقدم الخاصية من NotStarted الحالة، إلى Running، وأخيرا إلى Succeeded أو Failed. يمكنك استدعاء واجهة برمجة تطبيقات تجميع الدفعات GET بشكل دوري حتى تكون Succeeded الحالة التي تم إرجاعها أو Failed.

الحصول على تركيب الدفعة

للحصول على حالة مهمة تجميع الدفعات، قم بإجراء طلب HTTP GET باستخدام URI كما هو موضح في المثال التالي. استبدل YourSpeechKey بمفتاح مورد الكلام، واستبدل YourSpeechRegion بمنطقة موارد الكلام الخاصة بك.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

يجب أن تتلقى نص الاستجابة بالتنسيق التالي:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

من outputs.result، يمكنك تنزيل ملف ZIP يحتوي على الصوت (مثل 0001.wav)، والملخص، وتفاصيل التصحيح. لمزيد من المعلومات، راجع نتائج تجميع الدفعات.

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

لسرد جميع مهام تجميع الدفعات لمورد Speech، قم بإجراء طلب HTTP GET باستخدام URI كما هو موضح في المثال التالي. استبدل YourSpeechKey بمفتاح مورد Speech واستبدل YourSpeechRegion بمنطقة مورد Speech. اختياريا، يمكنك تعيين معلمات skip الاستعلام و maxpagesize (حتى 100) في عنوان URL. القيمة الافتراضية ل skip هي 0 والقيمة الافتراضية ل maxpagesize هي 100.

curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

يجب أن تتلقى نص الاستجابة بالتنسيق التالي:

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

تسرد value الخاصية في استجابة json طلبات التركيب الخاصة بك. القائمة مرقمة، ولا يزيد حجم الصفحة عن 100. "nextLink" يتم توفير الخاصية حسب الحاجة للحصول على الصفحة التالية من القائمة المرقمة.

حذف تركيب الدفعة

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

لحذف مهمة تجميع دفعية، قم بإجراء طلب HTTP DELETE باستخدام URI كما هو موضح في المثال التالي. استبدل YourSynthesisId بمعرف تركيب الدفعة، واستبدل YourSpeechKey بمفتاح مورد Speech الخاص بك، واستبدل YourSpeechRegion بمنطقة مورد Speech.

curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

تتضمن HTTP/1.1 204 No Content عناوين الاستجابة ما إذا كان طلب الحذف ناجحا.

نتائج تجميع الدفعات

بعد الحصول على وظيفة تركيب الدفعة مع status "نجاح"، يمكنك تنزيل نتائج إخراج الصوت. استخدم عنوان URL من outputs.result خاصية استجابة تجميع الدفعات.

للحصول على ملف نتائج تجميع الدفعات، قم بإجراء طلب HTTP GET باستخدام URI كما هو موضح في المثال التالي. استبدل YourOutputsResultUrl بعنوان URL من outputs.result خاصية الحصول على استجابة تجميع الدفعة. استبدل YourSpeechKey بمفتاح مورد الكلام.

curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip

تكون النتائج في ملف ZIP يحتوي على الصوت (مثل 0001.wav)، والملخص، وتفاصيل تتبع الأخطاء. البادئة ذات التعداد الرقمي لكل اسم ملف (موضحة أدناه ك [nnnn]) بنفس ترتيب إدخالات النص المستخدمة عند إنشاء تركيب الدفعة.

إشعار

[nnnn].debug.json يحتوي الملف على معرف نتيجة التركيب ومعلومات أخرى قد تساعد في استكشاف الأخطاء وإصلاحها. قد تتغير الخصائص التي يحتوي عليها، لذلك لا يجب أن تأخذ أي تبعيات على تنسيق JSON.

يحتوي ملف الملخص على نتائج التجميع لكل إدخال نص. فيما يلي مثال summary.json على الملف:

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

إذا تم طلب بيانات حد الجملة ("sentenceBoundaryEnabled": true)، فسيتم تضمين ملف مطابق [nnnn].sentence.json في النتائج. وبالمثل، إذا تم طلب بيانات حد كلمة ("wordBoundaryEnabled": true)، فسيتم تضمين ملف مطابق [nnnn].word.json في النتائج.

فيما يلي مثال لملف بيانات word مع كل من إزاحة الصوت والمدة بالمللي ثانية:

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

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

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

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

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

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

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

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

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

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

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

HTTP 200 OK

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

تم إنشاء HTTP 201

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

خطأ 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."
  }
}

مشاركة عبر

واجهة برمجة تطبيقات تجميع الدفعات للنص إلى كلام

إنشاء تركيب دفعي

الحصول على تركيب الدفعة

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

حذف تركيب الدفعة

نتائج تجميع الدفعات

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

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

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

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

HTTP 200 OK

تم إنشاء HTTP 201

خطأ HTTP 204

خطأ HTTP 400

خطأ HTTP 404

خطأ HTTP 429

خطأ HTTP 500

مثال على خطأ HTTP

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

الملاحظات

الملاحظات

الموارد الإضافية