Verbindung öffnen

Um eine Verbindung zum Service zu öffnen, rufen Sie die Methode /v1/synthesize über das Protokoll 'WebSocket Secure' (WSS) auf. Die Methode ist am folgenden Endpunkt verfügbar:

wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id}/v1/synthesize

Dabei gibt {location} an, an welcher Position Ihre Anwendung gehostet ist:

• us-south für Dallas
• us-east für Washington DC
• eu-de für Frankfurt
• au-syd für Sydney
• jp-tok für Tokio
• eu-gb für London
• kr-seo für Seoul

Und {instance_id} gibt die eindeutige ID der Serviceinstanz an.

In den Beispielen, die in der Dokumentation enthalten sind, wird wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} mit {ws_url} abgekürzt. Daher wird in allen WebSocket-Beispielen die Methode mit {ws_url}/v1/synthesize aufgerufen.

Ein WebSocket-Client ruft die Methode /v1/synthesize mit den folgenden Abfrageparametern auf, um eine authentifizierte Verbindung zum Service herzustellen:

access_token (erforderliche Zeichenfolge)

Übergeben Sie ein gültiges Zugriffstoken zur Authentifizierung beim Service. Sie müssen das Zugriffstoken nutzen, bevor es abläuft.

• IBM Cloud Übergeben Sie ein Identity and Access Management (IAM)-Zugriffstoken, um sich beim Dienst zu authentifizieren. Das IAM-Zugriffstoken wird in dem Aufruf anstelle eines API-Schlüssels übergeben. Weitere Informationen finden Sie unter Authentifizierung bei IBM Cloud.
• IBM Cloud Pak for DataIBM Software Hub Übergeben Sie ein Zugriffstoken wie den Authorization-Header einer HTTP-Anfrage. Weitere Informationen finden Sie unter Authentifizierung bei IBM Cloud Pak for Data.

voice (optionale Zeichenfolge)

Gibt die Stimme an, von der der Text in der Audioausgabe gesprochen werden soll. Mit der Methode /v1/voices können Sie die aktuelle Liste der unterstützten Stimmen abrufen. Lassen Sie den Parameter aus, wenn die Standardstimme verwendet werden soll. Weitere Informationen finden Sie unter Sprachen und Stimmen und Verwenden der Standardstimme.

customization_id (optionale Zeichenfolge)

Gibt die global eindeutige ID (GUID) für ein angepasstes Modell an, das für die Synthese verwendet werden soll. Ein angegebenes angepasstes Modell muss mit der Sprache der Stimme übereinstimmen, die für die Synthese verwendet wird. Wenn Sie eine Anpassungs-ID angeben, müssen Sie die Anforderung mit den Berechtigungsnachweisen für die Instanz des Service ausführen, der Eigner des angepassten Modells ist. Lassen Sie den Parameter weg, um die angegebene Stimme ohne Anpassung zu verwenden. Weitere Informationen enthält der Abschnitt Wissenswertes über die Anpassung.

rate_percentage (optional integer)

Gibt die globale Sprechgeschwindigkeit für die gesamte Syntheseanforderung an. Die Sprechgeschwindigkeit ist die Geschwindigkeit, mit der der Dienst den Text spricht, den er in Sprache umwandelt. Eine höhere Rate bewirkt, dass der Text schneller gesprochen wird; eine niedrigere Rate bewirkt, dass der Text langsamer gesprochen wird. Der Parameter ändert die Standardrate pro Stimme für eine gesamte Anfrage. Weitere Informationen finden Sie unter Ändern der Sprechgeschwindigkeit.

pitch_percentage (optional integer)

Gibt die globale Sprechstimme für die gesamte Syntheseanforderung an. Die Sprechstimmlage ist der Tonfall der Sprache, die der Dienst synthetisiert. Sie gibt an, wie hoch oder tief der Ton der Stimme vom Zuhörer wahrgenommen wird. Eine höhere Tonhöhe führt dazu, dass die Sprache in einem höheren Ton gesprochen wird; eine niedrigere Tonhöhe führt dazu, dass die Sprache in einem tieferen Ton gesprochen wird. Der Parameter ändert die Standardtonhöhe pro Stimme für eine gesamte Anfrage. Weitere Informationen finden Sie unter Ändern der Sprechstimmlage.

spell_out_mode (optionale Zeichenfolge)

Gibt bei deutschen Stimmen an, wie die einzelnen Zeichen einer Zeichenkette geschrieben werden sollen. Standardmäßig buchstabiert der Dienst die einzelnen Zeichen in der gleichen Geschwindigkeit, in der er den Text für eine Sprache synthetisiert. Mit diesem Parameter können Sie den Dienst anweisen, einzelne Zeichen langsamer zu buchstabieren, in Gruppen von einem singles), zwei pairs) oder drei triples). Weitere Informationen finden Sie unter Festlegen der Schreibweise von Zeichenfolgen.

x-watson-metadata (optionale Zeichenfolge)

Ordnet den Daten, die über die Verbindung übertragen werden, eine Kunden-ID zu. Der Parameter akzeptiert das Argument customer_id={id}; hierbei steht id für eine zufällige oder generische Zeichenfolge, die den Daten zugeordnet werden soll. Das Argument für den Parameter muss URL-codiert sein (z. B. customer_id%3dmy_customer_ID). Standardmäßig wird den Daten keine Kunden-ID zugeordnet. Weitere Informationen finden Sie unter Informationssicherheit.

x-watson-learning-opt-out (optionaler boolescher Wert)

IBM Cloud Gibt an, ob der Dienst Protokolle über Anfragen und Ergebnisse erstellt, die über die Verbindung gesendet werden. Wenn Sie nicht zulassen möchten, dass Ihre Daten von IBM für die allgemeine Verbesserung des Service verwendet werden, geben Sie für diesen Parameter true an. Durch Ihre Ablehnung wird IBM angewiesen, keine Benutzerdaten (Text oder Audiodaten) für Ihre Anforderung auf Platte zu schreiben. Sie können sich auch auf der Ebene des Kontos abmelden. Weitere Informationen finden Sie im Abschnitt Anforderungsprotokollierung.

Das folgende Snippet mit JavaScript-Code öffnet eine Verbindung zum Service. Im Aufruf der Methode /v1/synthesize werden die Abfrageparameter voice und access_token übergeben; ersterer weist den Service an, die Stimme 'Allison' für amerikanisches Englisch zu verwenden. Sobald die Verbindung hergestellt ist, werden die Ereignislistener (onOpen(), onClose() usw.) so definiert, dass sie auf Ereignisse des Service reagieren.

var access_token = '{access_token}';
var wsURI = '{ws_url}/v1/synthesize'
  + '?access_token=' + access_token
  + '&voice=en-US_AllisonV3Voice';
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };
websocket.onclose = function(evt) { onClose(evt) };
websocket.onmessage = function(evt) { onMessage(evt) };
websocket.onerror = function(evt) { onError(evt) };

Eingabetext senden

Um aus Text synthetisch Sprache zu erstellen, übergibt der Client eine einfache JSON-Textnachricht mit den folgenden Parametern an den Service:

text (erforderliche Zeichenfolge)

Gibt den Text an, aus dem synthetisch Sprache erstellt werden soll. Der Client kann einfachen Text oder mit SSML annotierten Text übergeben. Der Client kann mit der Anforderung Eingabetext in einer Größe von maximal 5 KB übergeben. Die Begrenzung bezieht jeden gegebenenfalls angegebenen SSML-Code ein. Weitere Informationen finden Sie unter Eingabetext angeben sowie in den dort folgenden Abschnitten. (Die SSML-Eingabe kann auch das Element <mark> enthalten. Weitere Informationen finden Sie unter SSML-Markup eingeben.)

accept (erforderliche Zeichenfolge)

Gibt das angeforderte Format (MIME-Typ) der Audioausgabe an. Verwenden Sie den Wert */*, um das Standardaudioformat audio/ogg;codecs=opus anzufordern. Weitere Informationen finden Sie unter Audioformate verwenden.

Das Ogg-Audioformat wird vom Safari-Browser nicht unterstützt. Wenn Sie den Dienst Text to Speech mit dem Safari-Browser verwenden, müssen Sie ein anderes Format angeben, in dem der Dienst das Audio zurückgeben soll.

timings (optionale Zeichenfolge[ ])

Gibt an, dass der Service für alle Zeichenfolgen des Eingabetextes Worttaktinformationen zurückgeben soll. Der Service gibt die Start- und die Endzeit für jedes Token der Eingabe zurück. Geben Sie words als einziges Element des Arrays an, um den Worttakt anzufordern. Geben Sie ein leeres Array an oder lassen Sie den Parameter weg, damit keine Worttaktinformationen empfangen werden. Weitere Informationen finden Sie unter Generierung von Wort-Timings. Nicht unterstützt für japanischen Eingabetext.

Das folgende Snippet mit JavaScript-Code übergibt eine einfache Nachricht 'Hello world' als Eingabetext und fordert das Standardformat für die Audioausgabe an. Die Aufrufe sind in der für den Client definierten Funktion onOpen() enthalten, um sicherzustellen, dass sie erst gesendet werden, nachdem die Verbindung hergestellt wurde.

function onOpen(evt) {
  var message = {
    text: 'Hello world',
    accept: '*/*'
  };
  websocket.send(JSON.stringify(message));
}

Der Service antwortet auf diese Nachricht, indem er eine Textnachricht sendet, die das Format der Audioantwort bestätigt. Die folgende Antwort bestätigt das Standardaudioformat.

{
  'binary_streams': [
    {
      content_type: 'audio/ogg;codecs=opus'
    }
  ]
}

Antwort empfangen

Nachdem der Service das Audioformat bestätigt hat, sendet er die synthetisch erstellte Audioausgabe als binären Datenstrom im angegebenen Format. Bei Audioformaten, die einen Header enthalten (wie zum Beispiel audio/wav und audio/ogg) gibt der Service den Header zurück, bevor er die Audiodaten sendet. Der Header kann sich über mehrere binäre Antworten erstrecken. Bei allen Audioformaten muss der Client alle binären Antworten vom Service aneinanderfügen, um die vollständige Audioantwort zusammenzusetzen.

Zusätzlich zu einer Textnachricht, die das angeforderte Audioformat bestätigt, kann der Service auch Textnachrichten mit Warnungen oder Fehlern senden. Der Service sendet auch eine oder mehrere Textnachrichten mit Taktinformationen, wenn Folgendes zutrifft:

• Der Eingabetext enthält mindestens ein SSML-Element <mark>.
• Sie haben den Parameter timings in Verbindung mit der Anforderung angegeben.

Der Client kann Textnachrichten verarbeiten, indem er sie beantwortet, sie anzeigt oder sie zur Verwendung durch die Anwendung erfasst, falls sie zum Beispiel -Positionen enthalten.

Sobald der Service die synthetische Erstellung auf der Grundlage des Eingabetexts abgeschlossen und den Versand aller Binär- und Textnachrichten beendet hat, schließt er automatisch die WebSocket-Verbindung. Die folgende einfache Funktion onMessage() hängt vom Service empfangene Text- und Binärnachrichten an die je nach Typ geeigneten Variablen an. Wenn die Funktion onClose() ausgeführt wird, wurde der gesamte Audiodatenstrom empfangen und der Service sendet keine weiteren Binär- oder Textnachrichten.

var messages;
var audioStream;

function onMessage(evt) {
  if (typeof evt.data === string) {
    messages += evt.data;
  } else {
    console.log('Received ' + evt.data.size() + ' binary bytes');
    audioStream += evt.data;
  }
}

function onClose(evt) {
  // The service's response is complete.
}

WebSocket-Rückgabecodes

Der Service kann über die WebSocket-Verbindung die folgenden Rückgabecodes an den Client senden:

• 1000 gibt den normalen Abschluss der Verbindung an. Dies bedeutet, dass der Zweck erfüllt ist, zu dem die Verbindung hergestellt wurde.
• 1002 gibt an, dass der Service die Verbindung aufgrund eines Protokollfehlers schließt.
• 1006 gibt an, dass die Verbindung abnormal beendet wurde.
• 1009 gibt an, dass die Rahmengröße die Begrenzung von 4 MB überschritten hat.
• 1011 gibt an, dass der Service die Verbindung beendet, weil er eine unerwartete Bedingung festgestellt hat, die die Erfüllung der Anforderung verhindert (z. B. ein ungültiges Argument). Der Rückgabecode kann auch bedeuten, dass der Eingabetext zu umfangreich war.

Falls der Socket mit einem Fehler geschlossen wird, sendet der Service eine Informationsnachricht mit dem Format {"error": "Specific error message"} an den Client, bevor der Schließvorgang stattfindet. Der Service kann auch nicht schwerwiegende Warnungen für unbekannte Parameter senden. Weitere Informationen zu WebSocket-Rückgabecodes finden Sie im Request for Comments(RFC)6455 der Internet Engineering Task Force (IETF).

Bei den WebSocket-Implementierungen der SDKs können andere oder zusätzliche Antwortcodes zurückgegeben werden.

{
  "warnings": "Unknown arguments: invalid-parameter."
}