Batch synthesis API for text to speech

  • Cikk

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.

A Batch Synthesis API munkafolyamatának diagramja.

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 a voicesynthesisConfig. Az alábbi példában az inputKind "SSML" értékre van állítva, így nincs synthesisConfig 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

A maximálisan elfogadott JSON hasznos adatméret 2 megabájt. Minden Speech-erőforrás legfeljebb 300 kötegszintézisi feladatsal rendelkezhet, amelyek egyidejűleg futnak.

Adja meg a szükséges YourSynthesisId elérési utat. Egyedinek YourSynthesisId 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 , Runningvégül a vagy a felé kell haladnia SucceededFailed. 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.resultletö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.resultletö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 get batch synthesis response tulajdonság url-címétoutputs.result.

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 a lekérési kötegszintézis-válasz tulajdonságának outputs.resultURL-címét. 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-kérés (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 hagyja outputFormat ü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.
  • Olyan új kötegszintézisi feladatot próbált létrehozni, amely meghaladná a 300 aktív feladat korlátját. Minden Speech-erőforrás legfeljebb 300 kötegszintézisi feladatsal rendelkezhet, amelyek állapota nem "Sikeres" vagy "Sikertelen".

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."
  }
}

Következő lépések