Batchsynthese gebruiken voor tekst-naar-spraak-avatar

Artikel
01/13/2025

Met de batchsynthese-API voor tekst-naar-spraak-avatar kan de asynchrone synthese van tekst in een sprekende avatar als videobestand worden gebruikt. Uitgevers en platformen voor video-inhoud kunnen deze API gebruiken om avatarvideo-inhoud in een batch te maken. Deze aanpak kan geschikt zijn voor verschillende gebruiksvoorbeelden, zoals trainingsmateriaal, presentaties of advertenties.

De synthetische avatarvideo wordt asynchroon gegenereerd nadat het systeem tekstinvoer heeft ontvangen. De gegenereerde video-uitvoer kan worden gedownload in batchmodussynthese. U verzendt tekst voor synthese, peilt naar de synthesestatus en downloadt de video-uitvoer wanneer de status aangeeft dat de status is geslaagd. De tekstinvoerindelingen moeten tekst zonder opmaak of SSML-tekst (Speech Synthesis Markup Language) zijn.

Dit diagram biedt een algemeen overzicht van de werkstroom.

Als u batchsynthese wilt uitvoeren, kunt u de volgende REST API-bewerkingen gebruiken.

Bewerking	Methode	REST API-aanroep
Batchsynthese maken	PUT	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Batchsynthese ophalen	GET	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Batchsynthese vermelden	GET	avatar/batchsyntheses/?api-version=2024-08-01
Batchsynthese verwijderen	DELETE	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01

U kunt verwijzen naar de codevoorbeelden op GitHub.

Een batchsyntheseaanvraag maken

Sommige eigenschappen in JSON-indeling zijn vereist wanneer u een nieuwe batchsynthesetaak maakt. Andere eigenschappen zijn optioneel. Het antwoord van de batchsynthese bevat andere eigenschappen voor informatie over de synthesestatus en resultaten. De eigenschap bevat bijvoorbeeld outputs.result de locatie van waaruit u een videobestand met de avatarvideo kunt downloaden. Hier outputs.summarykunt u toegang krijgen tot de samenvattings- en foutopsporingsgegevens.

Als u een batchsyntheseaanvraag wilt indienen, maakt u de hoofdtekst van de HTTP POST-aanvraag aan de volgende instructies:

Stel de vereiste inputKind eigenschap in.
Als de inputKind eigenschap is ingesteld op PlainText, moet u ook de voice eigenschap instellen in de synthesisConfig. In het onderstaande voorbeeld is het inputKind ingesteld op SSML, dus de speechSynthesis is niet ingesteld.
Stel de vereiste SynthesisId eigenschap in. Kies een unieke SynthesisId voor dezelfde spraakresource. Het SynthesisId kan een tekenreeks van 3 tot 64 tekens zijn, inclusief letters, cijfers, '-' of '_', met de voorwaarde dat deze moet beginnen en eindigen met een letter of cijfer.
Stel de vereiste talkingAvatarCharacter en talkingAvatarStyle eigenschappen in. Hier vindt u ondersteunde avatartekens en -stijlen.
U kunt desgewenst de videoFormat, backgroundColoren andere eigenschappen instellen. Zie de eigenschappen van batchsynthese voor meer informatie.

Notitie

De maximale toegestane JSON-nettoladinggrootte is 500 kilobytes.

Elke Spraak-resource kan maximaal 200 batchsynthesetaken tegelijk uitvoeren.

De maximale lengte voor de uitvoervideo is momenteel 20 minuten, met mogelijke toenamen in de toekomst.

Als u een HTTP PUT-aanvraag wilt maken, gebruikt u de URI-indeling die in het volgende voorbeeld wordt weergegeven. Vervang door YourSpeechKey uw Spraak-resourcesleutel, YourSpeechRegion door uw spraakresourceregio en stel de eigenschappen van de aanvraagbody in zoals hierboven beschreven.

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"

U ontvangt een antwoordtekst in de volgende indeling:

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

De status eigenschap moet van NotStarted status naar Running en ten slotte naar Succeeded of Failedworden voortgezet. U kunt de GET-batchsynthese-API periodiek aanroepen totdat de geretourneerde status is Succeeded of Failed.

Batchsynthese ophalen

Als u de status van een batchsynthesetaak wilt ophalen, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld.

Vervang door YourSynthesisId uw batchsynthese-id, YourSpeechKey door uw Spraak-resourcesleutel en YourSpeechRegion door uw Spraak-resourceregio.

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

U ontvangt een antwoordtekst in de volgende indeling:

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

Vanuit het outputs.result veld kunt u een videobestand met de avatarvideo downloaden. Met outputs.summary het veld kunt u de samenvattings- en foutopsporingsgegevens downloaden. Zie batchsyntheseresultaten voor meer informatie over batchsyntheseresultaten.

Batchsynthese vermelden

Als u alle batchsynthesetaken voor uw Spraak-resource wilt weergeven, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld.

Vervang YourSpeechKey door uw Spraak-resourcesleutel en YourSpeechRegion door uw Spraak-resourceregio. U kunt desgewenst de skip en top (paginagrootte) queryparameters instellen in de URL. De standaardwaarde is skip 0 en de standaardwaarde is maxpagesize 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"

U ontvangt een antwoordtekst in de volgende indeling:

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

U outputs.resultkunt een videobestand met de avatarvideo downloaden. Hier outputs.summarykunt u toegang krijgen tot de samenvattings- en foutopsporingsgegevens. Zie batchsyntheseresultaten voor meer informatie.

De value eigenschap in het JSON-antwoord bevat uw syntheseaanvragen. De lijst is gepagineerd, met een maximale paginagrootte van 100. De nextLink eigenschap wordt indien nodig opgegeven om de volgende pagina van de gepagineerde lijst op te halen.

Batchsyntheseresultatenbestand ophalen

Zodra u een batchsynthesetaak krijgt met status 'Succeeded', kunt u de resultaten van de video-uitvoer downloaden. Gebruik de URL uit de outputs.result eigenschap van het antwoord voor batchsynthese ophalen.

Als u het batchsyntheseresultatenbestand wilt ophalen, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang YourOutputsResultUrl door de URL uit de outputs.result eigenschap van het antwoord voor batchsynthese ophalen. Vervang door YourSpeechKey uw Spraak-resourcesleutel.

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

Als u het samenvattingsbestand voor batchsynthese wilt ophalen, maakt u een HTTP GET-aanvraag met behulp van de URI, zoals wordt weergegeven in het volgende voorbeeld. Vervang YourOutputsResultUrl door de URL uit de outputs.summary eigenschap van het antwoord voor batchsynthese ophalen. Vervang door YourSpeechKey uw Spraak-resourcesleutel.

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

Het samenvattingsbestand bevat de syntheseresultaten voor elke tekstinvoer. Hier volgt een voorbeeld van summary.json bestand:

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

Batchsynthese verwijderen

Nadat u de resultaten van de audio-uitvoer hebt opgehaald en de geschiedenis van de batchsynthesetaak niet meer nodig hebt, kunt u deze verwijderen. De Speech-service behoudt elke synthesegeschiedenis gedurende maximaal 31 dagen of de duur die is opgegeven door de eigenschap van timeToLiveInHours de aanvraag, afhankelijk van wat eerder komt. De datum en tijd van automatische verwijdering, voor synthesetaken met de status Geslaagd of Mislukt, wordt berekend als de som van de lastActionDateTime en timeToLive eigenschappen.

Als u een batchsynthesetaak wilt verwijderen, maakt u een HTTP DELETE-aanvraag met behulp van de volgende URI-indeling. Vervang door YourSynthesisId uw batchsynthese-id, YourSpeechKey door uw Spraak-resourcesleutel en YourSpeechRegion door uw Spraak-resourceregio.

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

De antwoordheaders bevatten HTTP/1.1 204 No Content als de verwijderaanvraag is geslaagd.

Delen via

Batchsynthese gebruiken voor tekst-naar-spraak-avatar

Een batchsyntheseaanvraag maken

Batchsynthese ophalen

Batchsynthese vermelden

Batchsyntheseresultatenbestand ophalen

Batchsynthese verwijderen

Volgende stappen

Feedback

Aanvullende resources