Come usare la sintesi batch per l'avatar di sintesi vocale (anteprima)
Nota
L'avatar di sintesi vocale è attualmente disponibile in anteprima pubblica. Questa versione di anteprima viene fornita senza un contratto di servizio e non è consigliabile per i carichi di lavoro di produzione. Alcune funzionalità potrebbero non essere supportate o potrebbero presentare funzionalità limitate. Per altre informazioni, vedere le Condizioni supplementari per l'uso delle anteprime di Microsoft Azure.
L'API di sintesi batch per l'avatar sintesi vocale (anteprima) consente la sintesi asincrona del testo in un avatar parlabile come file video. Gli editori e le piattaforme di contenuto video possono usare questa API per creare contenuto video 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 avatar sintetico verrà generato in modo asincrono dopo che il sistema riceve l'input di testo. L'output video generato può essere scaricato nella sintesi in modalità batch. Si invia testo per la sintesi, si esegue il polling dello stato di sintesi e si scarica l'output video quando lo stato indica l'esito positivo. I formati di input di testo devono essere testo normale o testo SSML (Speech Synthesis Markup Language).
Questo diagramma offre una panoramica generale del flusso di lavoro.
Per eseguire la sintesi batch, è possibile usare le operazioni API REST seguenti.
| Operazione | Method | Chiamata API REST |
|---|---|---|
| Creare la sintesi batch | PUT | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
| Ottenere la sintesi batch | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
| Elencare la sintesi batch | GET | avatar/batchsyntheses/?api-version=2024-04-15-preview |
| Eliminare la sintesi batch | DELETE | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
È possibile fare riferimento agli esempi di codice in GitHub.
Creare una richiesta di sintesi batch
Alcune proprietà in formato JSON sono necessarie quando si crea un nuovo processo di sintesi batch. Altre proprietà sono facoltative. La risposta di sintesi batch include altre proprietà per fornire informazioni sullo stato e sui risultati della sintesi. Ad esempio, la outputs.result proprietà contiene il percorso da cui è possibile scaricare un file video contenente il video 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à obbligatoria
inputKind. - Se la
inputKindproprietà è impostata suPlainText, è necessario impostare anche lavoiceproprietà insynthesisConfig. Nell'esempio seguente,inputKindè impostato suSSML, quindi nonspeechSynthesisè impostato. - Impostare la proprietà obbligatoria
SynthesisId. Scegliere un valore univocoSynthesisIdper la stessa risorsa di riconoscimento vocale.SynthesisIdPuò essere una stringa da 3 a 64 caratteri, incluse lettere, numeri, '-' o '_', con la condizione che deve iniziare e terminare con una lettera o un numero. - Impostare le proprietà e
talkingAvatarStyleobbligatorietalkingAvatarCharacter. Qui è possibile trovare i caratteri e gli stili avatar supportati. - Facoltativamente, è possibile impostare le
videoFormatproprietà ,backgroundColore altre. Per altre informazioni, vedere 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 aumenti 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-04-15-preview"
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 status proprietà deve passare dallo NotStarted stato 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-04-15-preview" -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"
}
}
outputs.result Dal campo è possibile scaricare un file video contenente il video avatar. Il outputs.summary campo consente di scaricare i dettagli di riepilogo e debug. Per altre informazioni sui risultati della sintesi batch, vedere 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 skip query 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-04-15-preview" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Si riceve un corpo della risposta nel formato seguente:
{
"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-04-15-preview&skip=2&maxpagesize=2"
}
Da outputs.resultè possibile scaricare un file video contenente il video avatar. Da outputs.summaryè possibile accedere ai dettagli di riepilogo e debug. Per altre informazioni, vedere Risultati della sintesi batch.
La value proprietà nella risposta JSON elenca le richieste di sintesi. L'elenco è impaginato, con dimensioni massime di pagina pari a 100. La nextLink proprietà viene fornita in base alle esigenze per ottenere la pagina successiva dell'elenco impaginato.
Ottenere il file dei risultati della sintesi batch
Dopo aver visualizzato un processo di sintesi batch con status "Succeeded", è possibile scaricare i risultati dell'output video. Usare l'URL dalla outputs.result proprietà della risposta di sintesi batch get.
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 dalla outputs.result proprietà della risposta di sintesi batch get. 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 outputs.summary proprietà della risposta di sintesi batch get. 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 aver recuperato i risultati dell'output audio e non è più necessaria la cronologia dei processi di sintesi batch, è possibile eliminarli. Il servizio Di riconoscimento vocale mantiene ogni cronologia di sintesi per un massimo di 31 giorni o la durata specificata dalla proprietà della timeToLiveInHours richiesta, a qualsiasi ora arriva prima. La data e l'ora dell'eliminazione automatica, per i processi di sintesi con lo stato "Succeeded" o "Failed" viene calcolata come somma delle lastActionDateTime proprietà 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-04-15-preview" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Le intestazioni di risposta includono HTTP/1.1 204 No Content se la richiesta di eliminazione ha avuto esito positivo.
Passaggi successivi
Commenti e suggerimenti
Presto disponibile: Nel corso del 2024 verranno gradualmente disattivati i problemi di GitHub come meccanismo di feedback per il contenuto e ciò verrà sostituito con un nuovo sistema di feedback. Per altre informazioni, vedere https://aka.ms/ContentUserFeedback.
Invia e visualizza il feedback per