Freigeben über

Eigenschaften der Batchsynthese für Text-zu-Sprache

  • Artikel

Wichtig

Die API für die Batchsynthese ist allgemein verfügbar. Die Long Audio-API wird am 1. April 2027 eingestellt. Weitere Informationen finden Sie unter Migrieren zur Batchsynthese-API.

Die Batchsynthese-API kann eine große Menge von Texteingaben (lang und kurz) asynchron synthetisieren. Herausgeber und Plattformen für Audioinhalte können lange Audioinhalte in einem Batch erstellen. Beispiel: Audiobücher, Nachrichtenartikel und Dokumente. Die Batchsynthese-API kann synthetisierte Audiodaten von mehr als 10 Minuten Länge erstellen.

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 der Batchsynthese-Ergebnisdateien mit Audioausgabe und Protokollen.

Eigenschaften der Batchsynthese

Die Eigenschaften der Batchsynthese werden in der folgenden Tabelle erläutert.

Eigenschaft BESCHREIBUNG
createdDateTime Das Datum und die Uhrzeit der Erstellung des Batchsyntheseauftrags.

Diese Eigenschaft ist schreibgeschützt.
customVoices Die Zuordnung des Namens einer benutzerdefinierten Stimme zu ihrer Bereitstellungs-ID.

Beispiel: "customVoices": {"your-custom-voice-name": "502ac834-6537-4bc3-9fd6-140114daa66d"}

Sie können den Namen der Stimme in Ihrer synthesisConfig.voice (wenn der inputKind auf "PlainText" festgelegt ist) oder innerhalb des SSML-Texts von inputs verwenden (wenn inputKind auf "SSML" festgelegt ist).

Diese Eigenschaft ist erforderlich, um eine benutzerdefinierte Stimme zu verwenden. Wenn Sie versuchen, eine benutzerdefinierte Stimme zu verwenden, die hier nicht definiert ist, gibt der Dienst einen Fehler zurück.
description Die Beschreibung der Batchsynthese.

Diese Eigenschaft ist optional.
id Die Auftrags-ID für die Batchsynthese, die Sie im Pfad übergeben haben.

Diese Eigenschaft ist im Pfad erforderlich.
inputs Der zu synthetisierende unformatierte oder SSML-Text.

Wenn der inputKind auf "PlainText" festgelegt ist, geben Sie unformatierten Text an, wie hier gezeigt: "inputs": [{"text": "The rainbow has seven colors."}]. Wenn der inputKind auf "SSML" festgelegt ist, geben Sie Text in der Speech Synthesis Markup Language (SSML) an, wie hier gezeigt: "inputs": [{"text": "<speak version='\''1.0'\'' xml:lang='\''en-US'\''><voice xml:lang='\''en-US'\'' xml:gender='\''Female'\'' name='\''en-US-AvaMultilingualNeural'\''>The rainbow has seven colors.</voice></speak>"}].

Fügen Sie bis zu 1.000 Textobjekte ein, wenn Sie mehrere Audioausgabedateien benötigen. Hier sehen Sie einen Beispieleingabetext, der in zwei Audioausgabedateien synthetisiert werden soll: "inputs": [{"text": "synthesize this to a file"},{"text": "synthesize this to another file"}]. Wenn die properties.concatenateResult-Eigenschaft jedoch auf true festgelegt ist, werden alle synthetisierten Ergebnisse in dieselbe Audioausgabedatei geschrieben.

Sie benötigen keine separaten Texteingaben für neue Absätze. Innerhalb jeder der (bis zu 1.000) Texteingaben können Sie neue Absätze mithilfe der Zeichenfolge „\r\n“ (Zeilenumbruch) angeben. Hier sehen Sie einen Beispieleingabetext mit zwei Absätzen, die in dieselbe Audioausgabedatei synthetisiert werden sollten: "inputs": [{"text": "synthesize this to a file\r\nsynthesize this to another paragraph in the same file"}]

Es gibt keine Absatzbeschränkungen, aber die maximale JSON-Nutzdatengröße (einschließlich aller Texteingaben und anderen Eigenschaften) beträgt 2 MB.

Diese Eigenschaft ist erforderlich, wenn Sie einen neuen Batchsyntheseauftrag erstellen. Diese Eigenschaft ist nicht in der Antwort enthalten, wenn Sie den Syntheseauftrag abrufen.
internalId Die interne Auftrags-ID der Batchsynthese.

Diese Eigenschaft ist schreibgeschützt.
lastActionDateTime Das Datum und die Uhrzeit der letzten Änderung des status-Eigenschaftswerts.

Diese Eigenschaft ist schreibgeschützt.
outputs.result Der Speicherort der Batchsynthese-Ergebnisdateien mit Audioausgabe und Protokollen.

Diese Eigenschaft ist schreibgeschützt.
properties Ein definierter Satz optionaler Konfigurationseinstellungen für die Batchsynthese.
properties.sizeInBytes Die Größe der Audioausgabe in Byte.

Diese Eigenschaft ist schreibgeschützt.
properties.billingDetails Die Anzahl der Wörter, die von customNeuralCharacters im Gegensatz zu neuralCharacters (vordefinierten) Stimmen verarbeitet und abgerechnet wurden.

Diese Eigenschaft ist schreibgeschützt.
properties.concatenateResult Bestimmt, ob das Ergebnis verkettet werden soll. Dieser optionale bool-Wert („true“ oder „false“) ist standardmäßig „false“.
properties.decompressOutputFiles Bestimmt, ob die Syntheseergebnisdateien im Zielcontainer entzippt werden sollen. Diese Eigenschaft kann nur festgelegt werden, wenn die destinationContainerUrl-Eigenschaft festgelegt wurde. Dieser optionale bool-Wert („true“ oder „false“) ist standardmäßig „false“.
properties.destinationContainerUrl Die Ergebnisse der Batchsynthese können in einem beschreibbaren Azure-Container gespeichert werden. Wenn Sie für SAS-Token (Shared Access Signature) keinen Container angeben, speichert der Speech-Dienst die Ergebnisse in einem von Microsoft verwalteten Container. SAS mit gespeicherten Zugriffsrichtlinien wird nicht unterstützt. Wenn der Syntheseauftrag gelöscht wird, werden die Ergebnisdaten ebenfalls gelöscht.

Diese optionale Eigenschaft ist nicht in der Antwort enthalten, wenn Sie den Syntheseauftrag abrufen.
properties.destinationPath Der Präfixpfad, mit dem Batchsyntheseergebnisse gespeichert werden können. Wenn Sie keinen Präfixpfad angeben, ist der Standardpräfixpfad YourSpeechResourceId/YourSynthesisId.

Diese optionale Eigenschaft kann nur festgelegt werden, wenn die destinationContainerUrl-Eigenschaft festgelegt wurde.
properties.durationInMilliseconds Die Dauer der Audioausgabe in Millisekunden.

Diese Eigenschaft ist schreibgeschützt.
properties.failedAudioCount Die Anzahl der fehlgeschlagenen Batchsyntheseeingaben für die Audioausgabe.

Diese Eigenschaft ist schreibgeschützt.
properties.outputFormat Das Audioausgabeformat.

Informationen zu den akzeptierten Werten finden Sie unter Audioausgabeformate. Das Standardausgabeformat ist riff-24khz-16bit-mono-pcm.
properties.sentenceBoundaryEnabled Bestimmt, ob Satzbegrenzungsdaten generiert werden sollen. Dieser optionale bool-Wert („true“ oder „false“) ist standardmäßig „false“.

Wenn Satzbegrenzungsdaten angefordert werden, wird eine entsprechende [nnnn].sentence.json-Datei mit in die Ergebnisse aufgenommen.
properties.succeededAudioCount Die Anzahl der erfolgreichen Batchsyntheseeingaben für die Audioausgabe.

Diese Eigenschaft ist schreibgeschützt.
properties.timeToLiveInHours Eine Dauer (in Stunden) nach dem Erstellen des Syntheseauftrags, wenn die Syntheseergebnisse automatisch gelöscht werden. Diese optionale Einstellung beträgt standardmäßig 744 (31 Tage). Die maximale Gültigkeitsdauer beträgt 31 Tage. Datum und Uhrzeit der automatischen Löschung (bei Syntheseaufträgen mit dem Status „Erfolgreich“ oder „Fehler“) entsprechen den Eigenschaften lastActionDateTime + timeToLiveInHours.

Andernfalls können Sie die Synthesemethode delete aufrufen, um den Auftrag früher zu entfernen.
properties.wordBoundaryEnabled Bestimmt, ob Wortbegrenzungsdaten generiert werden sollen. Dieser optionale bool-Wert („true“ oder „false“) ist standardmäßig „false“.

Wenn Wortbegrenzungsdaten angefordert werden, wird eine entsprechende [nnnn].word.json-Datei mit in die Ergebnisse aufgenommen.
status Der Verarbeitungsstatus der Batchsynthese.

Der Status sollte von „NotStarted“ über „Running“ und schließlich zu entweder zu „Erfolgreich“ oder „Fehler“ fortschreiten.

Diese Eigenschaft ist schreibgeschützt.
synthesisConfig Die Konfigurationseinstellungen, die für die Batchsynthese von unformatiertem Text verwendet werden sollen.

Diese Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.backgroundAudio Hintergrundaudio für jede Audioausgabe.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.backgroundAudio.fadein Die Einblendedauer der Hintergrundaudiodatei in Millisekunden. Der Standardwert ist 0, was dem „Nicht einblenden“ entspricht. Zulässige Werte: 0 bis 10000 (einschließlich).

Weitere Informationen finden Sie in der Attributtabelle im Abschnitt zum Hinzufügen von Hintergrundaudio in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.backgroundAudio.fadeout Die Ausblendedauer der Hintergrundaudiodatei in Millisekunden. Der Standardwert ist 0, was „Nicht ausblenden“ entspricht. Zulässige Werte: 0 bis 10000 (einschließlich).

Weitere Informationen finden Sie in der Attributtabelle im Abschnitt zum Hinzufügen von Hintergrundaudio in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.backgroundAudio.src Der URI-Speicherort der Hintergrundaudiodatei.

Weitere Informationen finden Sie in der Attributtabelle im Abschnitt zum Hinzufügen von Hintergrundaudio in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese Eigenschaft ist erforderlich, wenn synthesisConfig.backgroundAudio festgelegt wurde.
synthesisConfig.backgroundAudio.volume Die Lautstärke der Hintergrundaudiodatei. Zulässige Werte: 0 bis 100 (einschließlich). Der Standardwert ist 1.

Weitere Informationen finden Sie in der Attributtabelle im Abschnitt zum Hinzufügen von Hintergrundaudio in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.pitch Die Tonhöhe der Audioausgabe.

Informationen zu den akzeptierten Werten finden Sie in der Tabelle zum Anpassen der Prosodie in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.rate Die Rate der Audioausgabe.

Informationen zu den akzeptierten Werten finden Sie in der Tabelle zum Anpassen der Prosodie in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.role Bei einigen Stimmen können Sie das Sprechrollenspiel anpassen. Die Stimme kann ein anderes Alter und Geschlecht imitieren, aber der Name der Stimme ändert sich nicht. Beispielsweise kann eine männliche Stimme die Tonhöhe erhöhen und die Intonation so ändern, dass eine weibliche Stimme imitiert wird, aber der Stimmname wird nicht geändert. Wenn die Rolle fehlt oder für Ihre Stimme nicht unterstützt wird, wird dieses Attribut ignoriert.

Informationen zu den verfügbaren Sprechweisen pro Stimme finden Sie unter Sprachstile und -rollen.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.speakerProfileId Die Sprecherprofil-ID einer personalisierten Stimme.

Informationen zu den verfügbaren Basismodellnamen für personalisierte Stimmen finden Sie im Artikel zur Integration von personalisierten Stimmen.
Informationen zum Abrufen der Sprecherprofil-ID finden Sie im Artikel zu Sprachen- und Stimmenunterstützung.

Diese Eigenschaft ist erforderlich, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.style Für einige Stimmen können Sie die Sprechweise anpassen, um verschiedene Emotionen wie Fröhlichkeit, Empathie oder Ruhe auszudrücken. Sie können die Stimme auch für verschiedene Szenarios wie den Kundendienst, Nachrichtenbeiträge und die Verwendung des Sprach-Assistenten optimieren.

Informationen zu den verfügbaren Sprechweisen pro Stimme finden Sie unter Sprachstile und -rollen.

Diese optionale Eigenschaft ist nur verfügbar, wenn synthesisConfig.style festgelegt ist.
synthesisConfig.styleDegree Die Intensität der Sprechweise. Sie können eine kräftigere oder sanftere Sprechweise angeben, um die Sprache ausdrucksstärker oder gedämpfter zu gestalten. Der Bereich der akzeptierten Werte ist: 0,01 bis einschließlich 2. Der Standardwert ist 1, d. h. die vordefinierte Intensität für die Sprechweise. Die minimale Einheit ist 0,01, was zu einer leichten Tendenz zur Zielsprechweise führt. Ein Wert von 2 führt zu einer Verdoppelung der standardmäßigen Intensität der Sprechweise. Wenn der Stilgrad fehlt oder für Ihre Stimme nicht unterstützt wird, wird dieses Attribut ignoriert.

Informationen zu den verfügbaren Sprechweisen pro Stimme finden Sie unter Sprachstile und -rollen.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.voice Die Stimme, die die Audioausgabe spricht.

Informationen zu den verfügbaren vordefinierten neuronalen Stimmen finden Sie unter Unterstützung von Sprachen und Stimmen. Zum Verwenden einer benutzerdefinierten Stimme müssen Sie in der Eigenschaft customVoices eine gültige Zuordnung von benutzerdefinierter Stimme und Bereitstellungs-ID angeben. Um eine personalisierte Stimme zu verwenden, müssen Sie die synthesisConfig.speakerProfileId-Eigenschaft angeben.

Diese Eigenschaft ist erforderlich, wenn inputKind auf "PlainText" festgelegt ist.
synthesisConfig.volume Die Lautstärke der Audioausgabe.

Informationen zu den akzeptierten Werten finden Sie in der Tabelle zum Anpassen der Prosodie in der SSML-Dokumentation (Speech Synthesis Markup Language). Ungültige Werte werden ignoriert.

Diese optionale Eigenschaft ist nur verfügbar, wenn inputKind auf "PlainText" festgelegt ist.
inputKind Gibt an, ob die Texteigenschaft inputs sich auf unformatierten Text oder SSML beziehen soll. Die möglichen Werte sind „PlainText“ und „SSML“ (ohne Beachtung der Groß-/Kleinschreibung). Wenn der inputKind auf "PlainText" festgelegt ist, müssen Sie auch die Stimmeigenschaft synthesisConfig festlegen.

Diese Eigenschaft ist obligatorisch.

Wartezeit bei der Batchsynthese und bewährte Methoden

Bei der Verwendung der Batchsynthese zum Generieren der synthetisierten Spracheingabe ist es wichtig, die Wartezeit zu berücksichtigen und bewährte Methoden zu befolgen, um optimale Ergebnisse zu erzielen.

Wartezeit bei der Batchsynthese

Die Wartezeit bei der Batchsynthese hängt von verschiedenen Faktoren ab, u. a. von der Komplexität des Eingabetexts, der Anzahl der Eingaben im Batch und den Verarbeitungsfunktionen der zugrunde liegenden Hardware.

Die Wartezeit für die Batchsynthese ist wie folgt (ungefähre Angaben):

  • Die Wartezeit von 50 % der synthetisierten Sprachausgaben beträgt 10 bis 20 Sekunden.

  • Die Wartezeit von 95 % der synthetisierten Sprachausgaben beträgt max. 120 Sekunden.

Bewährte Methoden

Wenn Sie die Batchsynthese für Ihre Anwendung in Betracht ziehen, sollten Sie abwägen, ob die Wartezeit Ihren Anforderungen entspricht. Wenn die Wartezeit der gewünschten Leistung entspricht, kann die Batchsynthese eine geeignete Wahl sein. Wenn die Wartezeit jedoch nicht Ihren Anforderungen entspricht, können Sie die Verwendung der Echtzeit-API in Erwägung ziehen.

HTTP-Statuscodes

In diesem Abschnitt werden die HTTP-Antwortcodes und -Nachrichten von der Batchsynthese-API ausführlich erläutert.

HTTP 200 OK

„HTTP 200 OK“ gibt an, dass die Anforderung erfolgreich war.

HTTP 201 Created

„HTTP 201 Created“ gibt an, dass die Anforderung zum Erstellen der Batchsynthese (über HTTP POST) erfolgreich war.

HTTP-Fehler 204

Ein HTTP-Fehler 204 gibt an, dass die Anforderung erfolgreich war, die Ressource aber nicht vorhanden ist. Zum Beispiel:

  • Sie haben versucht, einen Syntheseauftrag abzurufen oder zu löschen, der nicht vorhanden ist.
  • Sie haben einen Syntheseauftrag erfolgreich gelöscht.

HTTP-Fehler 400

Hier sehen Sie Beispiele, die zum Fehler 400 führen können:

  • Das outputFormat wird nicht unterstützt oder ist ungültig. Geben Sie einen gültigen Wert für das Format an, oder lassen Sie outputFormat leer, um die Standardeinstellung zu verwenden.
  • Die Anzahl der angeforderten Texteingaben überschreitet den Grenzwert von 10.000.
  • Sie haben versucht, eine ungültige Bereitstellungs-ID oder eine benutzerdefinierte Stimme zu verwenden, die nicht erfolgreich bereitgestellt wurde. Vergewissern Sie sich, dass die Speech-Ressource Zugriff auf die benutzerdefinierte Stimme hat und die benutzerdefinierte Stimme erfolgreich bereitgestellt wurde. Sie müssen außerdem sicherstellen, dass die Zuordnung von {"your-custom-voice-name": "your-deployment-ID"} in Ihrer Batchsyntheseanforderung zutreffend ist.
  • Sie haben versucht, eine F0-Speech-Ressource zu verwenden, die Region unterstützt aber nur den Tarif Standard für Speech-Ressourcen.

HTTP-Fehler 404

Die angegebene Entität wurde nicht gefunden. Stellen Sie sicher, dass die Synthese-ID korrekt ist.

HTTP-Fehler 429

Es gibt zu viele aktuelle Anforderungen. Jede Clientanwendung kann innerhalb von 10 Sekunden bis zu 100 Anforderungen für jede Speech-Ressource einreichen. Verringern Sie die Anzahl der Anforderungen pro Sekunde.

HTTP-Fehler 500

Der interne Serverfehler HTTP 500 gibt an, dass bei der Anforderung ein Fehler aufgetreten ist. Der Antworttext enthält die Fehlermeldung.

HTTP-Fehlerbeispiel

Hier sehen Sie eine Beispielanforderung, die zu einem HTTP 400-Fehler führt, da die inputs-Eigenschaft zum Erstellen eines Auftrags benötigt wird.

curl -v -X PUT -H "Ocp-Apim-Subscription-Key: YourSpeechKey" -H "Content-Type: application/json" -d '{
    "inputKind": "SSML"
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

In diesem Fall enthalten die Antwortheader HTTP/1.1 400 Bad Request.

Der Antworttext ähnelt dem folgenden JSON-Beispiel:

{
  "error": {
    "code": "BadRequest",
    "message": "The inputs is required."
  }
}

Nächste Schritte