Come usare la sintesi batch per l'avatar di sintesi vocale

Articolo
01/13/2025

L'API di sintesi batch per l'avatar di sintesi vocale consente la sintesi asincrona del testo in un avatar parlante come file video. Gli editori e le piattaforme di contenuto video possono usare questa API per creare contenuti video con avatar in un batch. Questo approccio può essere adatto a vari casi d'uso, ad esempio materiali di formazione, presentazioni o annunci pubblicitari.

Il video dell’avatar sintetico verrà generato in modo asincrono dopo che il sistema riceve l'input di testo. L'output video generato può essere scaricato come sintesi in modalità batch. È necessario inviare il testo per la sintesi, eseguire il polling dello stato di sintesi e scaricare l'output video quando lo stato indica l'esito positivo dell’operazione. I formati di input di testo devono essere testo normale o testo markup per sintesi vocale (SSML).

Questo diagramma offre una panoramica di alto livello del flusso di lavoro.

Per eseguire la sintesi batch, è possibile usare le seguenti operazioni API REST.

Operazione	Method	Chiamata API REST
Creare la sintesi batch	PUT	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Ottenere la sintesi batch	GET	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01
Elencare la sintesi batch	GET	avatar/batchsyntheses/?api-version=2024-08-01
Eliminare la sintesi batch	DELETE	avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01

È possibile fare riferimento ai codici di esempio in GitHub.

Creare una richiesta di sintesi batch

Quando si crea un nuovo processo di sintesi batch, sono necessarie alcune proprietà in formato JSON. Le altre proprietà sono facoltative. La risposta di sintesi batch include altre proprietà volte a fornire informazioni sullo stato e sui risultati della sintesi. Ad esempio, la proprietà outputs.result contiene il percorso da cui è possibile scaricare un file video contenente il video dell’avatar. Da outputs.summary, è possibile accedere ai dettagli di riepilogo e debug.

Per inviare una richiesta di sintesi batch, costruire il corpo della richiesta HTTP POST seguendo queste istruzioni:

Impostare la proprietà inputKind necessaria.
Se la proprietà inputKind è impostata su PlainText, è necessario impostare anche la proprietà voice in synthesisConfig. Nell'esempio seguente, inputKind è impostato su SSML, quindi speechSynthesis non è impostato.
Impostare la proprietà SynthesisId necessaria. Scegliere un SynthesisId univoco per la stessa risorsa vocale. SynthesisId può essere una stringa da 3 a 64 caratteri, inclusi lettere, numeri, '-' o '_', a condizione che inizi e termini con una lettera o un numero.
Impostare le proprietà talkingAvatarCharacter e talkingAvatarStyle necessarie. È possibile trovare i caratteri e gli stili avatar supportati qui.
Facoltativamente, è possibile impostare le proprietà videoFormat, backgroundColor e altre. Per ulteriori informazioni, consultare Proprietà di sintesi batch.

Nota

La dimensione massima del payload JSON accettata è di 500 kilobyte.

Ogni risorsa voce può avere fino a 200 processi di sintesi batch in esecuzione simultaneamente.

La lunghezza massima per il video di output è attualmente di 20 minuti, con potenziali incrementi in futuro.

Per effettuare una richiesta HTTP PUT, usare il formato URI illustrato nell'esempio seguente. Sostituire YourSpeechKey con la chiave della risorsa Voce, YourSpeechRegion con l'area della risorsa Voce e impostare le proprietà del corpo della richiesta come descritto in precedenza.

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"

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

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

La proprietà status deve passare dallo stato NotStarted a Running e infine a Succeeded o Failed. È possibile chiamare periodicamente l'API di sintesi batch GET fino a quando lo stato restituito non è Succeeded o Failed.

Ottenere la sintesi batch

Per recuperare lo stato di un processo di sintesi batch, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente.

Sostituire YourSynthesisId con l'ID di sintesi batch, YourSpeechKey con la chiave della risorsa Voce e YourSpeechRegion con l'area della risorsa Voce.

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

Dovrebbe essere visualizzato un corpo della risposta nel formato seguente:

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

È possibile scaricare un file video contenente il video avatar dal campo outputs.result. Il campo outputs.summary consente di scaricare i dettagli di riepilogo e debug. Per ulteriori informazioni sui risultati della sintesi batch, consultare Risultati della sintesi batch.

Elencare la sintesi batch

Per elencare tutti i processi di sintesi batch per la risorsa Voce, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente.

Sostituire YourSpeechKey con la chiave della risorsa Voce e YourSpeechRegion con l'area della risorsa Voce. Facoltativamente, è possibile impostare i parametri di query skip e top (dimensioni pagina) nell'URL. Il valore predefinito per skip è 0 e il valore predefinito per 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"

Si riceverà un corpo della risposta nel seguente formato:

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

È possibile scaricare un file video contenente il video avatar da outputs.result. Da outputs.summary, è possibile accedere ai dettagli di riepilogo e debug. Per ulteriori informazioni, consultare Risultati della sintesi batch.

La proprietà value nella risposta JSON elenca le richieste di sintesi. L'elenco è suddiviso in pagine di dimensione massima pari a 100. La proprietà nextLink viene fornita in base alle esigenze per ottenere la pagina successiva dell'elenco impaginato.

Ottenere il file dei risultati della sintesi batch

Dopo aver ottenuto un processo di sintesi batch con status "Succeeded", è possibile scaricare i risultati dell'output video. Usare l'URL dalla proprietà outputs.result della risposta ottieni sintesi batch.

Per ottenere il file dei risultati della sintesi batch, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente. Sostituire YourOutputsResultUrl con l'URL della proprietà outputs.result della risposta alla richiesta di sintesi batch. Sostituire YourSpeechKey con la chiave della risorsa Voce.

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

Per ottenere il file di riepilogo della sintesi batch, eseguire una richiesta HTTP GET usando l'URI, come illustrato nell'esempio seguente. Sostituire YourOutputsResultUrl con l'URL dalla proprietà outputs.summary della risposta ottieni sintesi batch. Sostituire YourSpeechKey con la chiave della risorsa Voce.

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

Il file di riepilogo contiene i risultati di sintesi per ogni input di testo. Di seguito è riportato un esempio di file summary.json:

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

Eliminare la sintesi batch

Dopo che i risultati dell’output audio sono stati recuperati e la cronologia dei processi di sintesi batch non è più necessaria, è possibile eliminarla. Il servizio cognitivo di Azure per la voce conserva ogni cronologia di sintesi per un massimo di 31 giorni o per la durata specificata dalla proprietà timeToLiveInHours della richiesta, a seconda di quale scada prima. La data e l'ora dell'eliminazione automatica per processi di sintesi con lo stato "Succeeded" o "Failed" viene calcolata come somma delle proprietà lastActionDateTime e timeToLive.

Per eliminare un processo di sintesi batch, effettuare una richiesta HTTP DELETE usando il formato URI seguente. Sostituire YourSynthesisId con l'ID di sintesi batch, YourSpeechKey con la chiave della risorsa Voce e YourSpeechRegion con l'area della risorsa Voce.

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

Le intestazioni della risposta includeranno HTTP/1.1 204 No Content se la richiesta di eliminazione ha avuto esito positivo.

Condividi tramite

Come usare la sintesi batch per l'avatar di sintesi vocale

Creare una richiesta di sintesi batch

Ottenere la sintesi batch

Elencare la sintesi batch

Ottenere il file dei risultati della sintesi batch

Eliminare la sintesi batch

Passaggi successivi

Commenti e suggerimenti

Risorse aggiuntive