Använda batchsyntes för text till tal-avatar

Artikel
01/13/2025

Batchsyntes-API:et för text till tal-avatar möjliggör asynkron syntes av text till en talande avatar som en videofil. Utgivare och videoinnehållsplattformar kan använda det här API:et för att skapa avatarvideoinnehåll i en batch. Den metoden kan vara lämplig för olika användningsfall, till exempel utbildningsmaterial, presentationer eller annonser.

Den syntetiska avatarvideon genereras asynkront när systemet har fått textindata. De genererade videoutdata kan laddas ned i batchlägessyntes. Du skickar text för syntes, söker efter syntesstatus och laddar ned videoutdata när statusen indikerar att den lyckades. Textinmatningsformaten 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å.

Om du vill utföra batchsyntes kan du använda följande REST API-åtgärder.

Åtgärd	Method	REST API-anrop
Skapa batchsyntes	PUT	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Hämta batchsyntes	GET	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Lista batchsyntes	GET	avatar/batchsyntheses/?api-version=2024-08-01
Ta bort batchsyntes	DELETE	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01

Du kan läsa kodexemplen på GitHub.

Skapa en batchsyntesbegäran

Vissa egenskaper i JSON-format krävs när du skapar ett nytt batchsyntesjobb. Andra egenskaper är valfria. Batchsyntessvaret innehåller andra egenskaper för att ge information om syntesstatus och resultat. Egenskapen innehåller till exempel outputs.result platsen där du kan ladda ned en videofil som innehåller avatarvideon. Från outputs.summarykan du komma åt sammanfattnings- och felsökningsinformationen.

Om du vill skicka en batchsyntesbegäran skapar du HTTP POST-begärandetexten enligt följande instruktioner:

Ange den obligatoriska inputKind egenskapen.
Om egenskapen inputKind är inställd på PlainTextmåste du också ange voice egenskapen i synthesisConfig. I exemplet nedan inputKind är inställt på SSML, så speechSynthesis att inte anges.
Ange den obligatoriska SynthesisId egenskapen. Välj en unik SynthesisId för samma talresurs. SynthesisId Kan vara en sträng på 3 till 64 tecken, inklusive bokstäver, siffror, "-" eller "_", med villkoret att den måste starta och sluta med en bokstav eller siffra.
Ange nödvändiga talkingAvatarCharacter egenskaper och talkingAvatarStyle egenskaper. Du hittar avatartecken och formatmallar som stöds här.
Du kan också ange videoFormategenskaperna , backgroundColoroch andra. Mer information finns i egenskaper för batchsyntes.

Kommentar

Den maximala tillåtna JSON-nyttolasten är 500 kilobyte.

Varje Speech-resurs kan ha upp till 200 batchsyntesjobb som körs samtidigt.

Den maximala längden för utdatavideon är för närvarande 20 minuter, med potentiella ökningar i framtiden.

Om du vill göra en HTTP PUT-begäran använder du det URI-format som visas i följande exempel. Ersätt YourSpeechKey med din Speech-resursnyckel med YourSpeechRegion 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 '{
    "inputKind": "SSML",
    "inputs": [
        {
         "content": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"
        }
    ],
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting"
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/my-job-01?api-version=2024-08-01"

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

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "NotStarted",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:08.9487012Z",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    }
}

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

Hämta batchsyntes

Om du vill hämta status för ett batchsyntesjobb gör du en HTTP GET-begäran med hjälp av URI:n enligt följande exempel.

Ersätt YourSynthesisId med ditt batchsyntes-ID, YourSpeechKey med din Speech-resursnyckel och YourSpeechRegion med din Speech-resursregion.

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

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

{
    "id": "my-job-01",
    "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
    "status": "Succeeded",
    "createdDateTime": "2024-03-06T07:34:08.9487009Z",
    "lastActionDateTime": "2024-03-06T07:34:12.5698769",
    "inputKind": "SSML",
    "customVoices": {},
    "properties": {
        "timeToLiveInHours": 744,
        "sizeInBytes": 344460,
        "durationInMilliseconds": 2520,
        "succeededCount": 1,
        "failedCount": 0,
        "billingDetails": {
            "neuralCharacters": 29,
            "talkingAvatarDurationSeconds": 2
        }
    },
    "avatarConfig": {
        "talkingAvatarCharacter": "lisa",
        "talkingAvatarStyle": "graceful-sitting",
        "videoFormat": "Mp4",
        "videoCodec": "hevc",
        "subtitleType": "soft_embedded",
        "bitrateKbps": 2000,
        "customized": false
    },
    "outputs": {
        "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
        "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
    }
}

Från fältet outputs.result kan du ladda ned en videofil som innehåller avatarvideon. Med outputs.summary fältet kan du ladda ned sammanfattnings- och felsökningsinformationen. Mer information om batchsyntesresultat finns i batchsyntesresultat.

Lista batchsyntes

Om du vill visa en lista över alla batchsyntesjobb för din Speech-resurs 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 YourSpeechRegion med din Speech-resursregion. Du kan också ange skip frågeparametrarna och top (sidstorleken) 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/avatar/batchsyntheses?skip=0&maxpagesize=2&api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

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

{
    "value": [
        {
            "id": "my-job-02",
            "internalId": "14c25fcf-3cb6-4f46-8810-ecad06d956df",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:52:23.9054709Z",
            "lastActionDateTime": "2024-03-06T07:52:29.3416944",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 502676,
                "durationInMilliseconds": 2950,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 32,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "casual-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "h264",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        },
        {
            "id": "my-job-01",
            "internalId": "5a25b929-1358-4e81-a036-33000e788c46",
            "status": "Succeeded",
            "createdDateTime": "2024-03-06T07:34:08.9487009Z",
            "lastActionDateTime": "2024-03-06T07:34:12.5698769",
            "inputKind": "SSML",
            "customVoices": {},
            "properties": {
                "timeToLiveInHours": 744,
                "sizeInBytes": 344460,
                "durationInMilliseconds": 2520,
                "succeededCount": 1,
                "failedCount": 0,
                "billingDetails": {
                    "neuralCharacters": 29,
                    "talkingAvatarDurationSeconds": 2
                }
            },
            "avatarConfig": {
                "talkingAvatarCharacter": "lisa",
                "talkingAvatarStyle": "graceful-sitting",
                "videoFormat": "Mp4",
                "videoCodec": "hevc",
                "subtitleType": "soft_embedded",
                "bitrateKbps": 2000,
                "customized": false
            },
            "outputs": {
                "result": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/0001.mp4?SAS_Token",
                "summary": "https://stttssvcprodusw2.blob.core.windows.net/batchsynthesis-output/xxxxx/xxxxx/summary.json?SAS_Token"
            }
        }
    ],
    "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/?api-version=2024-08-01&skip=2&maxpagesize=2"
}

Från outputs.resultkan du ladda ned en videofil som innehåller avatarvideon. Från outputs.summarykan du komma åt sammanfattnings- och felsökningsinformationen. 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.

Hämta resultatfil för batchsyntes

När du får ett batchsyntesjobb med status "Lyckades" kan du ladda ned videoutdataresultatet. 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" > output.mp4

Om du vill hämta sammanfattningsfilen 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.summary egenskapen för hämtar batchsyntessvaret . Ersätt YourSpeechKey med din Speech-resursnyckel.

curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json

Sammanfattningsfilen innehåller syntesresultatet för varje textinmatning. Här är ett exempel summary.json fil:

{
  "jobID": "5a25b929-1358-4e81-a036-33000e788c46",
  "status": "Succeeded",
  "results": [
    {
      "texts": [
        "<speak version='1.0' xml:lang='en-US'><voice name='en-US-AvaMultilingualNeural'>The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "videoFileName": "244a87c294b94ddeb3dbaccee8ffa7eb/5a25b929-1358-4e81-a036-33000e788c46/0001.mp4",
      "TalkingAvatarCharacter": "lisa",
      "TalkingAvatarStyle": "graceful-sitting"
    }
  ]
}

Ta bort batchsyntes

När du har hämtat ljudutdataresultatet och inte längre behöver batchsyntesens jobbhistorik kan du ta bort den. Speech-tjänsten behåller varje synteshistorik i upp till 31 dagar eller den varaktighet som anges av begärans timeToLiveInHours egenskap, beroende på vilket som inträffar tidigare. Datum och tid för automatisk borttagning för syntesjobb med statusen "Lyckades" eller "Misslyckades" beräknas som summan av lastActionDateTime egenskaperna och timeToLive .

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

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

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

Dela via

Använda batchsyntes för text till tal-avatar

Skapa en batchsyntesbegäran

Hämta batchsyntes

Lista batchsyntes

Hämta resultatfil för batchsyntes

Ta bort batchsyntes

Nästa steg

Feedback

Ytterligare resurser