Batchsyntes-API för text till tal

  • Artikel

Api:et för Batch-syntes kan syntetisera en stor mängd textindata (lång och kort) asynkront. Utgivare och ljudinnehållsplattformar kan skapa långt ljudinnehåll i en batch. Till exempel ljudböcker, nyhetsartiklar och dokument. Batchsyntes-API:et kan skapa syntetiserat ljud längre än 10 minuter.

Viktigt!

Batch-syntes-API:et är allmänt tillgängligt. Long Audio-API:et dras tillbaka den 1 april 2027. Mer information finns i Migrera till batchsyntes-API.

Batchsyntes-API:et är asynkront och returnerar inte syntetiserat ljud i realtid. Du skickar textfiler som ska syntetiseras, söker efter status och laddar ned ljudutdata när statusen indikerar att det lyckades. Textinmatningarna måste vara Oformaterad text eller SSML-text (Speech Synthesis Markup Language).

Det här diagrammet ger en översikt över arbetsflödet på hög nivå.

Diagram över arbetsflödet för Batch Synthesis API.

Dricks

Du kan också använda Speech SDK för att skapa syntetiserat ljud längre än 10 minuter genom att iterera över texten och syntetisera den i segment. Ett C#-exempel finns i GitHub.

Du kan använda följande REST API-åtgärder för batchsyntes:

Åtgärd Method REST API-anrop
Skapa batchsyntes PUT texttospeech/batchsyntheses/YourSynthesisId
Hämta batchsyntes GET texttospeech/batchsyntheses/YourSynthesisId
Lista batchsyntes GET texttospeech/batchsyntheses
Ta bort batchsyntes DELETE texttospeech/batchsyntheses/YourSynthesisId

Kodexempel finns i GitHub.

Skapa batchsyntes

Om du vill skicka en batchsyntesbegäran skapar du sökvägen och brödtexten för HTTP PUT-begäran enligt följande instruktioner:

  • Ange den obligatoriska inputKind egenskapen.
  • Om egenskapen inputKind är inställd på "PlainText" måste du också ange voice egenskapen i synthesisConfig. I exemplet nedan inputKind är inställt på "SSML", så synthesisConfig är inte inställt.
  • Du kan också ange descriptionegenskaperna , timeToLiveInHoursoch andra. Mer information finns i egenskaper för batchsyntes.

Kommentar

Den maximala JSON-nyttolaststorleken som godkänns är 2 megabyte.

Ange vilken sökväg som krävs YourSynthesisId . Måste YourSynthesisId vara unik. Den måste vara 3–64 lång, innehåller endast siffror, bokstäver, bindestreck, understreck och punkter, startar och slutar med en bokstav eller siffra.

Gör en HTTP PUT-begäran med hjälp av URI:n enligt följande exempel. Ersätt YourSpeechKey med din Speech-resursnyckel, ersätt YourSpeechRegion med resursregionen Speech och ange egenskaperna för begärandetexten enligt beskrivningen ovan.

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"

Du bör få en svarstext i följande format:

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

Egenskapen status ska gå från NotStarted status, till Runningoch slutligen till Succeeded eller Failed. Du kan anropa API:et för GET-batchsyntes regelbundet tills den returnerade statusen är Succeeded eller Failed.

Hämta batchsyntes

Om du vill hämta status för batchsyntesjobbet gör du en HTTP GET-begäran med hjälp av URI:n enligt följande exempel. Ersätt YourSpeechKey med din Speech-resursnyckel och ersätt YourSpeechRegion med din Speech-resursregion.

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

Du bör få en svarstext i följande format:

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

Från outputs.resultkan du ladda ned en ZIP-fil som innehåller ljud (till exempel 0001.wav), sammanfattning och felsökningsinformation. Mer information finns i batchsyntesresultat.

Lista batchsyntes

Om du vill visa en lista över alla batchsyntesjobb för Speech-resursen gör du en HTTP GET-begäran med hjälp av URI:n enligt följande exempel. Ersätt YourSpeechKey med din Speech-resursnyckel och ersätt YourSpeechRegion med din Speech-resursregion. Du kan också ange skip frågeparametrarna och maxpagesize (upp till 100) i URL:en. Standardvärdet för skip är 0 och standardvärdet för maxpagesize är 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"

Du bör få en svarstext i följande format:

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

Från outputs.resultkan du ladda ned en ZIP-fil som innehåller ljud (till exempel 0001.wav), sammanfattning och felsökningsinformation. Mer information finns i batchsyntesresultat.

Egenskapen value i json-svaret visar en lista över dina syntesbegäranden. Listan är sidnumrerad med en maximal sidstorlek på 100. Egenskapen "nextLink" tillhandahålls efter behov för att hämta nästa sida i den sidnumrerade listan.

Ta bort batchsyntes

Ta bort historiken för batchsyntesjobbet när du har hämtat resultatet av ljudutdata. Speech-tjänsten behåller batchsynteshistoriken i upp till 31 dagar, eller varaktigheten för begärandeegenskapen timeToLiveInHours , beroende på vilket som inträffar tidigare. Datum och tid för automatisk borttagning (för syntesjobb med statusen "Lyckades" eller "Misslyckades") är lika lastActionDateTime + timeToLiveInHours med egenskaperna.

Om du vill ta bort ett batchsyntesjobb gör du en HTTP DELETE-begäran med hjälp av URI:n enligt följande exempel. Ersätt YourSynthesisId med ditt batchsyntes-ID, ersätt YourSpeechKey med din Speech-resursnyckel och ersätt YourSpeechRegion med din Speech-resursregion.

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

Svarshuvudena inkluderar HTTP/1.1 204 No Content om borttagningsbegäran lyckades.

Resultat av batchsyntes

När du har fått ett batchsyntesjobb med status "Lyckades" kan du ladda ned ljudutdataresultatet. Använd URL:en från outputs.result egenskapen för svaret hämta batchsyntes .

Om du vill hämta resultatfilen för batchsyntesen gör du en HTTP GET-begäran med hjälp av URI:n enligt följande exempel. Ersätt YourOutputsResultUrl med URL:en från outputs.result egenskapen för hämtar batchsyntessvaret . Ersätt YourSpeechKey med din Speech-resursnyckel.

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

Resultatet finns i en ZIP-fil som innehåller ljud (till exempel 0001.wav), sammanfattning och felsökningsinformation. Det numrerade prefixet för varje filnamn (visas nedan som [nnnn]) är i samma ordning som textinmatningarna som användes när du skapade batchsyntesen.

Kommentar

Filen [nnnn].debug.json innehåller resultat-ID för syntes och annan information som kan vara till hjälp vid felsökning. Egenskaperna som den innehåller kan ändras, så du bör inte ha några beroenden i JSON-formatet.

Sammanfattningsfilen innehåller syntesresultatet för varje textinmatning. Här är en exempelfil 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"
      }
    }
  ]
}

Om meningsgränsdata begärdes ("sentenceBoundaryEnabled": true) inkluderas en motsvarande [nnnn].sentence.json fil i resultatet. På samma sätt inkluderas en motsvarande [nnnn].word.json fil i resultatet om ordgränsdata begärdes ("wordBoundaryEnabled": true).

Här är ett exempel på en orddatafil med både ljudförskjutning och varaktighet i millisekunder:

[
  {
    "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
  }
]

Svarstid och metodtips för batchsyntes

När du använder batchsyntes för att generera syntetiserat tal är det viktigt att överväga svarstiden och följa metodtipsen för att uppnå optimala resultat.

Svarstid i batchsyntes

Svarstiden i batchsyntesen beror på olika faktorer, inklusive komplexiteten i indatatexten, antalet indata i batchen och bearbetningsfunktionerna för den underliggande maskinvaran.

Svarstiden för batchsyntesen är följande (ungefär):

  • Svarstiden för 50 % av de syntetiserade talutdata är inom 10–20 sekunder.

  • Svarstiden för 95 % av de syntetiserade talutdata är inom 120 sekunder.

Bästa praxis

När du överväger batchsyntes för ditt program rekommenderar vi att du utvärderar om svarstiden uppfyller dina krav. Om svarstiden överensstämmer med önskad prestanda kan batchsyntes vara ett lämpligt val. Men om svarstiden inte uppfyller dina behov kan du överväga att använda realtids-API.

HTTP-statuskoder

Avsnittet beskriver HTTP-svarskoderna och meddelandena från batchsyntes-API:et.

HTTP 200 OK

HTTP 200 OK anger att begäran lyckades.

HTTP 201 har skapats

HTTP 201 Skapad anger att begäran om att skapa batchsyntes (via HTTP PUT) lyckades.

HTTP 204-fel

Ett HTTP 204-fel anger att begäran lyckades, men resursen finns inte. Till exempel:

  • Du försökte hämta eller ta bort ett syntesjobb som inte finns.
  • Du har tagit bort ett syntesjobb.

HTTP 400-fel

Här är exempel som kan resultera i 400-felet:

  • Stöds outputFormat inte eller är ogiltigt. Ange ett giltigt formatvärde eller lämna outputFormat tomt om du vill använda standardinställningen.
  • Antalet begärda textindata överskred gränsen på 10 000.
  • Du försökte använda ett ogiltigt distributions-ID eller en anpassad röst som inte har distribuerats. Kontrollera att Speech-resursen har åtkomst till den anpassade rösten och att den anpassade rösten har distribuerats. Du måste också se till att mappningen av {"your-custom-voice-name": "your-deployment-ID"} är korrekt i batchsyntesbegäran.
  • Du försökte använda en F0 Speech-resurs, men regionen stöder bara prisnivån Standard Speech-resurs.
  • Du försökte skapa ett nytt batchsyntesjobb som skulle överskrida gränsen på 300 aktiva jobb. Varje Speech-resurs kan ha upp till 300 batchsyntesjobb som inte har statusen "Lyckades" eller "Misslyckades".

HTTP 404-fel

Det går inte att hitta den angivna entiteten. Kontrollera att syntes-ID:t är korrekt.

HTTP 429-fel

Det finns för många nya begäranden. Varje klientprogram kan skicka upp till 100 begäranden per 10 sekunder för varje Speech-resurs. Minska antalet begäranden per sekund.

HTTP 500-fel

HTTP 500 Internt serverfel anger att begäran misslyckades. Svarstexten innehåller felmeddelandet.

HTTP-felexempel

Här är en exempelbegäran som resulterar i ett HTTP 400-fel, eftersom inputs egenskapen krävs för att skapa ett jobb.

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"

I det här fallet innehåller HTTP/1.1 400 Bad Requestsvarsrubrikerna .

Svarstexten liknar följande JSON-exempel:

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

Nästa steg