Verwenden der Batchsynthese für Text-zu-Sprache-Avatar
Die Batchsynthese-API für Text-zu-Sprache-Avatar ermöglicht die asynchrone Synthese von Text in einen sprechenden Avatar als Videodatei. Herausgeber und Videoinhaltsplattformen können diese API verwenden, um Avatarvideoinhalte in einem Batch zu erstellen. Dieser Ansatz kann für verschiedene Anwendungsfälle wie Schulungsmaterialien, Präsentationen oder Werbung geeignet sein.
Das synthetische Avatarvideo wird asynchron generiert, nachdem das System Texteingaben empfängt. Die generierte Videoausgabe kann in der Batchmodussynthese heruntergeladen werden. Sie übermitteln Text zur Synthese, abrufen den Synthesestatus und laden die Videoausgabe herunter, wenn der Status den Erfolg angibt. Die Texteingabeformate dürfen nur als unformatierter Text oder als SSML-Text (Speech Synthesis Markup Language) vorliegen.
Dieses Diagramm bietet eine allgemeine Übersicht über den Workflow.
Zum Ausführen der Batchsynthese können Sie die folgenden REST-API-Vorgänge verwenden.
Vorgang | Methode | REST-API-Aufruf |
---|---|---|
Erstellen einer Batchsynthese | PUT | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
Abrufen von Batchsynthese | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
Auflisten der Batchsynthese | GET | avatar/batchsyntheses/?api-version=2024-08-01 |
Löschen einer Batchsynthese | DELETE | avatar/batchsyntheses/{SynthesisId}?api-version=2024-08-01 |
Sie können sich auf die Codebeispiele auf GitHub beziehen.
Erstellen einer Batchsyntheseanforderung
Einige Eigenschaften im JSON-Format sind erforderlich, wenn Sie einen neuen Batchsyntheseauftrag erstellen. Andere Eigenschaften sind optional. Die Batchsyntheseantwort enthält weitere Eigenschaften, um Informationen über den Synthesestatus und die Ergebnisse bereitzustellen. Die Eigenschaft outputs.result
enthält beispielsweise den Speicherort, an dem Sie eine Videodatei herunterladen können, die das Avatarvideo enthält. Über outputs.summary
können Sie auf die Zusammenfassungs- und Debugdetails zugreifen.
Zum Einreichen einer Batchsyntheseanforderung erstellen Sie den HTTP POST-Anforderungstext gemäß den folgenden Anweisungen:
- Legen Sie die erforderliche
inputKind
-Eigenschaft fest. - Wenn die
inputKind
-Eigenschaft aufPlainText
festgelegt ist, müssen Sie außerdem dievoice
-Eigenschaft imsynthesisConfig
festlegen. Im folgenden Beispiel ist derinputKind
aufSSML
festgelegt, daher wirdspeechSynthesis
nicht festgelegt. - Legen Sie die erforderliche
SynthesisId
-Eigenschaft fest. Wählen Sie eine eindeutigeSynthesisId
für dieselbe Sprachressource aus. DieSynthesisId
kann eine Zeichenfolge von 3 bis 64 Zeichen sein, einschließlich Buchstaben, Zahlen, „-“ oder „_“, mit der Bedingung, dass sie mit einem Buchstaben oder einer Zahl beginnen und enden muss. - Legen Sie die erforderlichen
talkingAvatarCharacter
Eigenschaften undtalkingAvatarStyle
Eigenschaften fest. Sie finden unterstützte Avatarzeichen und Stile hier. - Optional können Sie die
videoFormat
, diebackgroundColor
und weitere Eigenschaften festlegen. Weitere Informationen finden Sie unter Batchsyntheseeigenschaften.
Hinweis
Die zulässige maximale JSON-Nutzlastgröße beträgt 500 Kilobyte.
Jede Speech-Ressource kann über bis zu 200 Batchsyntheseaufträge verfügen, die gleichzeitig ausgeführt werden.
Die maximale Länge für das Ausgabevideo beträgt derzeit 20 Minuten, mit potenziellen Erhöhungen in der Zukunft.
Um eine HTTP PUT-Anforderung zu erstellen, verwenden Sie das im folgenden Beispiel gezeigte URI-Format. Ersetzen Sie YourSpeechKey
durch Ihren Speech-Ressourcenschlüssel, ersetzen Sie YourSpeechRegion
durch die Region der Speech-Ressource, und legen Sie die Anforderungstexteigenschaften wie zuvor beschrieben fest.
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"
Sie sollten einen Antworttext im folgenden Format erhalten:
{
"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
}
}
Die Eigenschaft status
sollte vom Status NotStarted
über Running
bis zu schließlich Succeeded
oder Failed
fortschreiten. Sie können die -API zum Abrufen der Batchsynthese in regelmäßigen Abständen aufrufen, bis der zurückgegebene Status Succeeded
oder Failed
ist.
Abrufen von Batchsynthese
Zum Abrufen des Status des Batchsyntheseauftrags führen Sie eine HTTP GET-Anforderung unter Verwendung des URI aus, wie im folgenden Beispiel gezeigt.
Ersetzen Sie YourSynthesisId
durch Ihre Batchsynthese-ID, YourSpeechKey
durch den Schlüssel Ihrer Speech-Ressource und YourSpeechRegion
durch die Region Ihrer Speech-Ressource.
curl -v -X GET "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Sie sollten einen Antworttext im folgenden Format erhalten:
{
"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"
}
}
Aus dem outputs.result
Feld können Sie eine Videodatei herunterladen, die das Avatarvideo enthält. Mit dem outputs.summary
Feld können Sie die Zusammenfassungs- und Debugdetails herunterladen. Weitere Informationen zu Ergebnissen der Batchsynthese finden Sie unter Ergebnisse der Batchsynthese.
Auflisten der Batchsynthese
Zum Auflisten aller Batchsyntheseaufträge für die Speech-Ressource erstellen Sie eine HTTP GET-Anforderung mit dem URI, wie im folgenden Beispiel gezeigt.
Ersetzen Sie YourSpeechKey
durch den Schlüssel Ihrer Speech-Ressource und YourSpeechRegion
durch die Region Ihrer Speech-Ressource. Optional können Sie die Abfrageparameter skip
und top
(Seitengröße) in der URL festlegen. Der Standardwert von skip
ist 0, und der Standardwert von maxpagesize
ist 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"
Sie erhalten einen Antworttext im folgenden 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"
}
Von outputs.result
können Sie eine Videodatei herunterladen, die das Avatarvideo enthält. Über outputs.summary
können Sie auf die Zusammenfassungs- und Debugdetails zugreifen. Weitere Informationen finden Sie unter Ergebnisse der Batchsynthese.
Die value
-Eigenschaft in der JSON-Antwort listet Ihre Syntheseanforderungen auf. Die Liste ist paginiert, mit einer maximalen Seitengröße von 100. Die nextLink
-Eigenschaft wird bei Bedarf angegeben, um die nächste Seite der paginierten Liste abzurufen.
Ergebnisdatei der Batchsynthese
Nachdem Sie einen Batchsyntheseauftrag mit status
„Erfolgreich“ erhalten haben, können Sie die Ergebnisse der Audioausgabe herunterladen. Verwenden Sie die URL aus der Eigenschaft outputs.result
der Antwort auf das Abrufen der Batchsynthese.
Zum Abrufen der Ergebnisdatei der Batchsynthese führen Sie eine HTTP GET-Anforderung unter Verwendung des URI aus, wie im folgenden Beispiel gezeigt. Ersetzen Sie YourOutputsResultUrl
durch die URL aus der outputs.result
-Eigenschaft der Antwort auf das Abrufen der Batchsynthese. Ersetzen Sie YourSpeechKey
durch Ihren Speech-Ressourcenschlüssel.
curl -v -X GET "YourOutputsResultUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > output.mp4
Zum Abrufen der Zusammenfassungsdatei der Batchsynthese führen Sie eine HTTP GET-Anforderung unter Verwendung des URI aus, wie im folgenden Beispiel gezeigt. Ersetzen Sie YourOutputsResultUrl
durch die URL aus der outputs.summary
-Eigenschaft der Antwort auf das Abrufen der Batchsynthese. Ersetzen Sie YourSpeechKey
durch Ihren Speech-Ressourcenschlüssel.
curl -v -X GET "YourOutputsSummaryUrl" -H "Ocp-Apim-Subscription-Key: YourSpeechKey" > summary.json
Die Zusammenfassungsdatei enthält die Syntheseergebnisse für jede Texteingabe. Hier ist eine Beispieldatei „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"
}
]
}
Löschen einer Batchsynthese
Nachdem Sie die Ergebnisse der Audioausgabe abgerufen haben und den Auftragsverlauf der Batchsynthese nicht mehr benötigen, können Sie ihn löschen. Der Spracherkennungsdienst behält jeden Syntheseverlauf für bis zu 31 Tage oder die durch die Eigenschaft der Anforderung timeToLiveInHours
angegebene Dauer bei, je nachdem, was früher eintritt. Das Datum und die Uhrzeit der automatischen Löschung für Syntheseaufträge mit dem Status „Erfolgreich“ oder „Fehlgeschlagen“ werden als Summe der Eigenschaften lastActionDateTime
und timeToLive
berechnet.
Zum Löschen des Batchsyntheseauftrags führen Sie eine HTTP DELETE-Anforderung unter Verwendung des des folgenden URI-Formats aus. Ersetzen Sie YourSynthesisId
durch Ihre Batchsynthese-ID, YourSpeechKey
durch den Schlüssel Ihrer Speech-Ressource und YourSpeechRegion
durch die Region Ihrer Speech-Ressource.
curl -v -X DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/avatar/batchsyntheses/YourSynthesisId?api-version=2024-08-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Die Antwortheader enthalten HTTP/1.1 204 No Content
, wenn die Löschanforderung erfolgreich war.