Batch synthesis API for text to speech
A Batch szintézis API nagy mennyiségű (hosszú és rövid) szövegbevitelt képes aszinkron módon szintetizálni. A közzétevők és a hangtartalom-platformok hosszú hangtartalmakat hozhatnak létre egy kötegben. Például: hangoskönyvek, hírcikkek és dokumentumok. A kötegelt szintézis API 10 percnél hosszabb szintetizált hangot hozhat létre.
Fontos
A Batch szintézis API általánosan elérhető. A Long Audio API 2027. április 1-jén megszűnik. További információ: Migrálás kötegelt szintézis API-ba.
A kötegelt szintézis API aszinkron, és nem ad vissza szintetizált hangot valós időben. Elküldheti a szintetizálandó szövegfájlokat, lekérdezheti az állapotot, és letöltheti a hangkimenetet, ha az állapot sikerességet jelez. A szövegbeviteleknek egyszerű szövegnek vagy beszédszintézisi korrektúranyelvnek (SSML) kell lenniük.
Ez a diagram magas szintű áttekintést nyújt a munkafolyamatról.
Tipp.
A Speech SDK-val 10 percnél hosszabb szintetizált hangot is létrehozhat a szöveg iterálásával és adattömbökben való szintetizálásával. C#-példa: GitHub.
A kötegszintézishez a következő REST API-műveleteket használhatja:
Művelet | Metódus | REST API-hívás |
---|---|---|
Kötegszintézis létrehozása | PUT |
texttospeech/batchsyntheses/YourSynthesisId |
Kötegszintézis lekérése | GET |
texttospeech/batchsyntheses/YourSynthesisId |
Kötegszintézis listázása | GET |
texttospeech/batchsyntheses |
Kötegszintézis törlése | DELETE |
texttospeech/batchsyntheses/YourSynthesisId |
A kódmintákért lásd a GitHubot.
Kötegszintézis létrehozása
Kötegszintézis-kérés elküldéséhez hozza létre a HTTP PUT kérelem elérési útját és törzsét az alábbi utasítások szerint:
- Állítsa be a szükséges
inputKind
tulajdonságot. - Ha a
inputKind
tulajdonság értéke "Egyszerű szöveg", akkor a tulajdonságot is be kell állítania avoice
synthesisConfig
. Az alábbi példában azinputKind
"SSML" értékre van állítva, így nincssynthesisConfig
beállítva. - Igény szerint beállíthatja a
description
,timeToLiveInHours
és egyéb tulajdonságokat is. További információ: kötegszintézis tulajdonságai.
Feljegyzés
Az elfogadott maximális JSON-hasznos adatméret 2 megabájt.
Adja meg a szükséges YourSynthesisId
elérési utat. Ennek YourSynthesisId
egyedinek kell lennie. 3-64 hosszúnak kell lennie, csak számokat, betűket, kötőjeleket, aláhúzásjeleket és pontokat tartalmaz, betűvel vagy számmal kezdődik és végződik.
Http PUT-kérés létrehozása az URI használatával az alábbi példában látható módon. Cserélje le YourSpeechKey
a Speech erőforráskulcsát, cserélje le YourSpeechRegion
a Speech erőforrásterületre, és állítsa be a kérés törzstulajdonságait a korábban leírtak szerint.
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"
A válasz törzsének a következő formátumban kell érkeznie:
{
"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
}
}
A status
tulajdonságnak az állapottól az állapotig NotStarted
, Running
végül a vagy a felé kell haladnia Succeeded
Failed
. A GET kötegelt szintézis API-t rendszeres időközönként meghívhatja, amíg a visszaadott állapot Succeeded
vagy Failed
.
Kötegszintézis lekérése
A kötegszintézisi feladat állapotának lekéréséhez hozzon létre egy HTTP GET kérést az URI használatával az alábbi példában látható módon. Cserélje le YourSpeechKey
a Speech erőforráskulcsot, és cserélje le YourSpeechRegion
a Speech erőforrásrégiójára.
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
A válasz törzsének a következő formátumban kell érkeznie:
{
"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"
}
}
Innen outputs.result
letölthet egy ZIP-fájlt, amely tartalmazza a hangokat (például 0001.wav
), összegzést és hibakeresési adatokat. További információkért tekintse meg a kötegszintézis eredményeit.
Kötegszintézis listázása
A Speech-erőforrás összes kötegelt szintézisi feladatának listázásához hozzon létre egy HTTP GET kérést az URI használatával az alábbi példában látható módon. Cserélje le YourSpeechKey
a Speech erőforráskulcsot, és cserélje le YourSpeechRegion
a Speech erőforrásrégiójára. Igény szerint beállíthatja a skip
lekérdezési paramétereket ( maxpagesize
legfeljebb 100) az URL-címben. Az alapértelmezett érték skip
0, az alapértelmezett érték maxpagesize
pedig 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"
A válasz törzsének a következő formátumban kell érkeznie:
{
"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"
}
Innen outputs.result
letölthet egy ZIP-fájlt, amely tartalmazza a hangokat (például 0001.wav
), összegzést és hibakeresési adatokat. További információkért tekintse meg a kötegszintézis eredményeit.
A value
json-válasz tulajdonsága felsorolja a szintéziskéréseket. A lista lapszámozott, maximális oldalmérete 100. A "nextLink"
tulajdonság szükség szerint meg van adva a lapszámozott lista következő oldalának lekéréséhez.
Kötegszintézis törlése
Törölje a kötegszintézisi feladat előzményeit a hangkimenet eredményeinek lekérése után. A Speech szolgáltatás legfeljebb 31 napig megőrzi a kötegszintézis előzményeit, vagy a kérelem timeToLiveInHours
tulajdonság időtartamát, attól függően, hogy melyik hamarabb érkezik. Az automatikus törlés dátuma és időpontja ("Sikeres" vagy "Sikertelen" állapotú szintézisfeladatok esetén) megegyezik a lastActionDateTime
+ timeToLiveInHours
tulajdonságokkal.
Kötegszintézisi feladat törléséhez hozzon létre egy HTTP DELETE kérést az URI használatával az alábbi példában látható módon. Cserélje le YourSynthesisId
a kötegszintézis azonosítójára, cserélje le YourSpeechKey
a Speech erőforráskulcsára, és cserélje le YourSpeechRegion
a Speech erőforrásrégiójára.
curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
A válaszfejlécek tartalmazzák HTTP/1.1 204 No Content
, hogy a törlési kérés sikeres volt-e.
Batch-szintézis eredményei
Miután lekérte a "Sikeres" kötegelt szintézisi feladatotstatus
, letöltheti a hangkimenet eredményeit. Használja a kötegelt szintézis GET válaszának tulajdonságából származó outputs.result
URL-címet.
A kötegszintézis eredményfájljának lekéréséhez hozzon létre egy HTTP GET kérést az URI használatával az alábbi példában látható módon. Cserélje le YourOutputsResultUrl
az URL-címet a outputs.result
batch synthesis GET válasz tulajdonságából. Cserélje le YourSpeechKey
a Speech erőforráskulcsot.
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > results.zip
Az eredmények egy ZIP-fájlban találhatók, amely tartalmazza a hang (például 0001.wav
), összegzés és hibakeresés részleteit. Az egyes fájlnevek számozott előtagja (alább látható) [nnnn]
ugyanabban a sorrendben van, mint a kötegszintézis létrehozásakor használt szövegbevitelek.
Feljegyzés
A [nnnn].debug.json
fájl tartalmazza a szintézis eredményazonosítóját és a hibaelhárításhoz esetleg szükséges egyéb információkat. A benne található tulajdonságok változhatnak, ezért nem szabad függőséget vállalnia a JSON formátumtól.
Az összefoglaló fájl tartalmazza az egyes szövegbevitelek összefoglaló eredményeit. Íme egy példafájl 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"
}
}
]
}
Ha a mondathatáradatokat kérték ("sentenceBoundaryEnabled": true
), akkor az eredmény tartalmaz egy megfelelő [nnnn].sentence.json
fájlt. Hasonlóképpen, ha a word határadatait kérték ("wordBoundaryEnabled": true
), akkor egy megfelelő [nnnn].word.json
fájl szerepel az eredmények között.
Íme egy példa szóadatfájl hangeltolással és időtartammal ezredmásodpercben:
[
{
"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
}
]
Batch-szintézis késése és ajánlott eljárások
Amikor kötegelt szintézist használ a szintetizált beszéd létrehozásához, fontos figyelembe venni a késést, és követni az optimális eredmények eléréséhez ajánlott eljárásokat.
Késés a kötegszintézisben
A kötegszintézis késése különböző tényezőktől függ, például a bemeneti szöveg összetettségétől, a kötegben lévő bemenetek számától és a mögöttes hardver feldolgozási képességeitől.
A kötegszintézis késése a következő (körülbelül):
A szintetizált beszédkimenetek 50%-ának késése 10–20 másodpercen belül van.
A szintetizált beszédkimenetek 95%-ának késése 120 másodpercen belül van.
Ajánlott eljárások
Az alkalmazás kötegelt szintézisének mérlegelésekor ajánlott felmérni, hogy a késés megfelel-e a követelményeknek. Ha a késés megfelel a kívánt teljesítménynek, a kötegszintézis megfelelő választás lehet. Ha azonban a késés nem felel meg az igényeinek, érdemes lehet valós idejű API-t használnia.
HTTP-állapotkódok
A szakasz a kötegelt szintézis API HTTP-válaszkódjait és üzeneteit ismerteti.
HTTP 200 OK
A HTTP 200 OK azt jelzi, hogy a kérés sikeres volt.
HTTP 201 létrehozva
A HTTP 201 Created azt jelzi, hogy a kötegszintézis létrehozási kérése (HTTP PUT-on keresztül) sikeres volt.
HTTP 204-hiba
A HTTP 204-hiba azt jelzi, hogy a kérés sikeres volt, de az erőforrás nem létezik. Példa:
- Olyan szintézisfeladatot próbált lekérni vagy törölni, amely nem létezik.
- Sikeresen törölt egy szintézisfeladatot.
HTTP 400-hiba
Íme néhány példa, amelyek a 400-ás hibát eredményezhetik:
- Ez
outputFormat
nem támogatott vagy érvénytelen. Adjon meg érvényes formátumértéket, vagy hagyjaoutputFormat
üresen az alapértelmezett beállítás használatához. - A kért szövegbevitelek száma meghaladta a 10 000-es korlátot.
- Érvénytelen üzembehelyezési azonosítót vagy nem sikeresen üzembe helyezett egyéni hangot próbált használni. Győződjön meg arról, hogy a Speech-erőforrás hozzáfér az egyéni hanghoz, és az egyéni hang üzembe helyezése sikeresen megtörtént. Azt is meg kell győződnie, hogy a leképezés
{"your-custom-voice-name": "your-deployment-ID"}
helyes a kötegszintézis-kérelemben. - F0 Speech-erőforrást próbált használni, de a régió csak a Standard Speech erőforrás tarifacsomagot támogatja.
HTTP 404-es hiba
A megadott entitás nem található. Győződjön meg arról, hogy a szintézis azonosítója megfelelő.
HTTP 429-hiba
Túl sok a legutóbbi kérés. Minden ügyfélalkalmazás legfeljebb 100 kérést küldhet 10 másodpercenként minden Speech-erőforráshoz. Csökkentse a másodpercenkénti kérelmek számát.
HTTP 500-as hiba
A HTTP 500 belső kiszolgáló hibája azt jelzi, hogy a kérés sikertelen volt. A válasz törzse tartalmazza a hibaüzenetet.
PÉLDA HTTP-hiba
Íme egy példakérés, amely HTTP 400-hibát eredményez, mivel a inputs
tulajdonság szükséges egy feladat létrehozásához.
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"
Ebben az esetben a válaszfejlécek a következők HTTP/1.1 400 Bad Request
: .
A válasz törzse a következő JSON-példához hasonlít:
{
"error": {
"code": "BadRequest",
"message": "The inputs is required."
}
}