Verwenden der Batchsynthese für Text-zu-Sprache-Avatar (Vorschau)
Hinweis
Der Text-zu-Sprache-Avatar ist derzeit als öffentliche Vorschauversion verfügbar. Diese Vorschau wird ohne Vereinbarung zum Servicelevel bereitgestellt und nicht für Produktionsworkloads empfohlen. Manche Features werden möglicherweise nicht unterstützt oder sind nur eingeschränkt verwendbar. Weitere Informationen finden Sie unter Zusätzliche Nutzungsbestimmungen für Microsoft Azure-Vorschauen.
Die Batchsynthese-API für Text-zu-Sprache-Avatar (Vorschau) 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-04-15-preview |
| Abrufen von Batchsynthese | GET | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
| Auflisten der Batchsynthese | GET | avatar/batchsyntheses/?api-version=2024-04-15-preview |
| Löschen einer Batchsynthese | DELETE | avatar/batchsyntheses/{SynthesisId}?api-version=2024-04-15-preview |
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 aufPlainTextfestgelegt ist, müssen Sie außerdem dievoice-Eigenschaft imsynthesisConfigfestlegen. Im folgenden Beispiel ist derinputKindaufSSMLfestgelegt, daher wirdspeechSynthesisnicht festgelegt. - Legen Sie die erforderliche
SynthesisId-Eigenschaft fest. Wählen Sie eine eindeutigeSynthesisIdfür dieselbe Sprachressource aus. DieSynthesisIdkann 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
talkingAvatarCharacterEigenschaften undtalkingAvatarStyleEigenschaften fest. Sie finden unterstützte Avatarzeichen und Stile hier. - Optional können Sie die
videoFormat, diebackgroundColorund 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-04-15-preview"
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-04-15-preview" -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-04-15-preview" -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-04-15-preview&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-04-15-preview" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"
Die Antwortheader enthalten HTTP/1.1 204 No Content, wenn die Löschanforderung erfolgreich war.
Nächste Schritte
Feedback
Bald verfügbar: Im Laufe des Jahres 2024 werden wir GitHub-Tickets als Feedbackmechanismus für Inhalte auslaufen lassen und es durch ein neues Feedbacksystem ersetzen. Weitere Informationen finden Sie unter: https://aka.ms/ContentUserFeedback.
Einreichen und Feedback anzeigen für