Batchsynthese-API für Text-zu-Sprache

  • Artikel

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.

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 ist asynchron und gibt synthetisierte Audiodaten nicht in Echtzeit zurück. Sie übermitteln Textdateien, die synthetisiert werden sollen, rufen den Status ab und laden die Audioausgabe herunter, wenn der Status „Erfolgreich“ ist. Die Texteingaben dürfen nur als unformatierter Text oder als SSML-Text (Speech Synthesis Markup Language) vorliegen.

Dieses Diagramm bietet eine allgemeine Übersicht über den Workflow.

Diagramm des Workflows für die Batchsynthese-API.

Tipp

Sie können das Speech-SDK auch verwenden, um synthetisierte Audiodaten zu erstellen, die länger als 10 Minuten sind, indem Sie den Text durchlaufen und ihn in Blöcken synthetisieren. Ein C#-Beispiel finden Sie unter GitHub.

Sie können die folgenden REST-API-Vorgänge für die Batchsynthese verwenden:

Vorgang Methode REST-API-Aufruf
Erstellen einer Batchsynthese PUT texttospeech/batchsyntheses/YourSynthesisId
Abrufen von Batchsynthese GET texttospeech/batchsyntheses/YourSynthesisId
Auflisten der Batchsynthese GET texttospeech/batchsyntheses
Löschen einer Batchsynthese DELETE texttospeech/batchsyntheses/YourSynthesisId

Codebeispiele finden Sie auf GitHub.

Erstellen einer Batchsynthese

Zum Einreichen einer Batchsyntheseanforderung erstellen Sie den HTTP PUT-Anforderungspfad und -text gemäß den folgenden Anweisungen:

  • Legen Sie die erforderliche inputKind-Eigenschaft fest.
  • Wenn die inputKind-Eigenschaft auf „PlainText“ festgelegt ist, müssen Sie außerdem die voice-Eigenschaft im synthesisConfig festlegen. Im folgenden Beispiel ist der inputKind auf „SSML“ festgelegt, daher wird synthesisConfig nicht festgelegt.
  • Optional können Sie die description, die timeToLiveInHours und weitere Eigenschaften festlegen. Weitere Informationen finden Sie unter Batchsyntheseeigenschaften.

Hinweis

Die zulässige maximale JSON-Nutzdatengröße beträgt 2 MB. Jede Speech-Ressource kann über bis zu 300 Batchsyntheseaufträge verfügen, die gleichzeitig ausgeführt werden.

Legen Sie die erforderliche YourSynthesisId im Pfad fest. Die YourSynthesisId muss eindeutig sein. Sie muss 3 bis 64 Zeichen lang sein, darf nur Ziffern, Buchstaben, Bindestriche, Unterstriche und Punkte enthalten und muss mit einem Buchstaben oder einer Ziffer beginnen und enden.

Erstellen Sie eine HTTP PUT-Anforderung mithilfe des URI, wie im folgenden -Beispiel gezeigt. 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 '{
    "description": "my ssml test",
    "inputKind": "SSML",
    "inputs": [
        {
            "content": "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
        }
    ],
    "properties": {
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "concatenateResult": false,
        "decompressOutputFiles": false
    }
}'  "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01"

Sie sollten einen Antworttext im folgenden Format erhalten:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "NotStarted",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.0097388Z",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": 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 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/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Sie sollten einen Antworttext im folgenden Format erhalten:

{
  "id": "YourSynthesisId",
  "internalId": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "createdDateTime": "2024-03-12T07:23:18.0097387Z",
  "lastActionDateTime": "2024-03-12T07:23:18.7979669",
  "inputKind": "SSML",
  "customVoices": {},
  "properties": {
    "timeToLiveInHours": 744,
    "outputFormat": "riff-24khz-16bit-mono-pcm",
    "concatenateResult": false,
    "decompressOutputFiles": false,
    "wordBoundaryEnabled": false,
    "sentenceBoundaryEnabled": false,
    "sizeInBytes": 120000,
    "succeededAudioCount": 1,
    "failedAudioCount": 0,
    "durationInMilliseconds": 2500,
    "billingDetails": {
      "neuralCharacters": 29
    }
  },
  "outputs": {
    "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/YourSynthesisId/results.zip?SAS_Token"
  }
}

Von outputs.result können Sie eine ZIP-Datei herunterladen, die die Audiodaten (z. B. 0001.wav), eine Zusammenfassung und Debugdetails enthält. Weitere Informationen 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 maxpagesize (max. 100) 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/texttospeech/batchsyntheses?api-version=2024-04-01&skip=1&maxpagesize=2" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Sie sollten einen Antworttext im folgenden Format erhalten:

{
  "value": [
    {
      "id": "my-job-03",
      "internalId": "5f7e9ab6-2c92-4dcb-b5ee-ec0983ee4db0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:32.5690441Z",
      "lastActionDateTime": "2024-03-12T07:28:33.0042293",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-03/results.zip?SAS_Token"
      }
    },
    {
      "id": "my-job-02",
      "internalId": "5577585f-4710-4d4f-aab6-162d14bd7ee0",
      "status": "Succeeded",
      "createdDateTime": "2024-03-12T07:28:29.6418211Z",
      "lastActionDateTime": "2024-03-12T07:28:30.0910306",
      "inputKind": "SSML",
      "customVoices": {},
      "properties": {
        "timeToLiveInHours": 744,
        "outputFormat": "riff-24khz-16bit-mono-pcm",
        "concatenateResult": false,
        "decompressOutputFiles": false,
        "wordBoundaryEnabled": false,
        "sentenceBoundaryEnabled": false,
        "sizeInBytes": 120000,
        "succeededAudioCount": 1,
        "failedAudioCount": 0,
        "durationInMilliseconds": 2500,
        "billingDetails": {
          "neuralCharacters": 29
        }
      },
      "outputs": {
        "result": "https://stttssvcuse.blob.core.windows.net/batchsynthesis-output/29f2105f997c4bfea176d39d05ff201e/my-job-02/results.zip?SAS_Token"
      }
    }
  ],
  "nextLink": "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses?skip=3&maxpagesize=2&api-version=2024-04-01"
}

Von outputs.result können Sie eine ZIP-Datei herunterladen, die die Audiodaten (z. B. 0001.wav), eine Zusammenfassung und Debugdetails enthält. 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.

Löschen einer Batchsynthese

Löschen Sie den Verlauf des Batchsyntheseauftrags, nachdem Sie die Ergebnisse der Audioausgabe abgerufen haben. Der Speech-Dienst bewahrt jeden Syntheseverlauf bis zu 31 Tage lang oder für die in der Anforderungseigenschaft timeToLiveInHours angegebene Dauer auf, je nachdem, was früher eintritt. Datum und Uhrzeit der automatischen Löschung (bei Syntheseaufträgen mit dem Status „Erfolgreich“ oder „Fehler“) entsprechen den Eigenschaften lastActionDateTime + timeToLiveInHours.

Zum Löschen des Batchsyntheseauftrags führen Sie eine HTTP DELETE-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 DELETE "https://YourSpeechRegion.api.cognitive.microsoft.com/texttospeech/batchsyntheses/YourSynthesisId?api-version=2024-04-01" -H "Ocp-Apim-Subscription-Key: YourSpeechKey"

Die Antwortheader enthalten HTTP/1.1 204 No Content, wenn die Löschanforderung erfolgreich war.

Ergebnisse 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" > results.zip

Die Ergebnisse befinden sich in einer ZIP-Datei, die die Audiodaten (z. B. 0001.wav), die Zusammenfassung und die Debugdetails enthält. Das nummerierte Präfix der einzelnen Dateinamen (unten als [nnnn] dargestellt) weist dieselbe Reihenfolge wie die Texteingaben auf, die zum Erstellen der Batchsynthese verwendet wurden.

Hinweis

Die [nnnn].debug.json-Datei enthält die Syntheseergebnis-ID und weitere Informationen, die bei der Problembehandlung hilfreich sein können. Die darin enthaltenen Eigenschaften können sich ändern, sodass Sie keine Abhängigkeiten vom JSON-Format akzeptieren sollten.

Die Zusammenfassungsdatei enthält die Syntheseergebnisse für jede Texteingabe. Hier ist ein Beispiel für eine summary.json-Datei angegeben:

{
  "jobID": "7ab84171-9070-4d3b-88d4-1b8cc1cb928a",
  "status": "Succeeded",
  "results": [
    {
      "contents": [
        "<speak version=\"1.0\" xml:lang=\"en-US\"><voice name=\"en-US-JennyNeural\">The rainbow has seven colors.</voice></speak>"
      ],
      "status": "Succeeded",
      "audioFileName": "0001.wav",
      "properties": {
        "sizeInBytes": "120000",
        "durationInMilliseconds": "2500"
      }
    }
  ]
}

Wenn Satzbegrenzungsdaten angefordert wurden ("sentenceBoundaryEnabled": true), wird eine entsprechende [nnnn].sentence.json-Datei in die Ergebnisse eingeschlossen. Analog dazu wird bei der Anforderung von Wortbegrenzungsdaten ("wordBoundaryEnabled": true) eine entsprechende [nnnn].word.json-Datei in die Ergebnisse aufgenommen.

Hier sehen Sie ein Beispiel für eine Wortdatendatei, die sowohl den Audiooffset als auch die Dauer in Millisekunden enthält:

[
  {
    "Text": "The",
    "AudioOffset": 50,
    "Duration": 137
  },
  {
    "Text": "rainbow",
    "AudioOffset": 200,
    "Duration": 350
  },
  {
    "Text": "has",
    "AudioOffset": 562,
    "Duration": 175
  },
  {
    "Text": "seven",
    "AudioOffset": 750,
    "Duration": 300
  },
  {
    "Text": "colors",
    "AudioOffset": 1062,
    "Duration": 625
  },
  {
    "Text": ".",
    "AudioOffset": 1700,
    "Duration": 100
  }
]

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 PUT) 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.
  • Sie haben versucht, einen neuen Batchsyntheseauftrag zu erstellen, der den Grenzwert von 300 aktiven Aufträgen überschreiten würde. Jede Speech-Ressource kann bis zu 300 Batchsyntheseaufträge aufweisen, die nicht den Status „Erfolgreich“ oder „Fehlerhaft“ haben.

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