Syntaxanforderungen

Beachten Sie beim Erstellen einer Spracherkennungsanforderung die folgenden Nutzungsvoraussetzungen:

• Bei Methodennamen muss die Groß-/Kleinschreibung beachtet werden.
• HTTP-Anforderungsheader sind von Groß-/Kleinschreibung unabhängig.
• Bei HTTP- und WebSocket-Abfrageparametern muss die Groß-/Kleinschreibung beachtet werden.
• Bei JSON-Feldnamen muss die Groß-/Kleinschreibung beachtet werden.
• Für alle Inhalte von JSON-Antworten wird der UTF-8-Zeichensatz verwendet.
• Geschweifte Klammern ({ }) werden in der Dokumentation zum Kennzeichnen von Variablenwerten verwendet. Beim Eingeben der Variablenwerte müssen die geschweiften Klammern weggelassen werden.

Beachten Sie außerdem die folgenden servicespezifischen Anforderungen:

• Sie müssen nur die Audioeingabedaten angeben. Alle anderen Parameter sind optional.
• Stellen Sie bei Bedarf sicher, dass der Parameter model angegeben wird, um ein Modell zu kennzeichnen, das für Ihre Sprache und Audiodaten geeignet ist.
• Wenn Sie einen ungültigen Abfrageparameter oder ein ungültiges JSON-Feld in der Eingabe angeben, enthält die Antwort ein Feld warnings, in dem das ungültige Argument beschrieben wird. Die Anforderung wird trotz der angegebenen Warnungen erfolgreich ausgeführt.

Audiodaten mit einer Anforderung senden

Die Audiodaten, die Sie an den Service übergeben, müssen in einem der vom Service unterstützten Formate vorliegen. Für die meisten Audiodaten kann der Service das Format automatisch erkennen. Bei einigen Audioformaten müssen Sie das Format mit dem Parameter Content-Type oder einem äquivalenten Parameter angeben. Weitere Informationen finden Sie unter Audioformate. (Zur Verdeutlichung ist in den folgenden Beispielen das Audioformat bei allen Anforderungen angegeben.)

Mit der WebSocket-Schnittstelle und der synchronen HTTP-Schnittstelle können Sie in einer einzelnen Anforderung Audiodaten mit einer Größe von maximal 100 MB übergeben. Mit der asynchronen HTTP-Schnittstelle können Sie Audiodaten mit einer maximalen Größe von 1 GB übergeben. Mit jeder Anforderung müssen Audiodaten mit einer Mindestgröße von 100 Byte gesendet werden.

Falls die Erkennung für große Mengen von Audiodaten erfolgen soll, können Sie die Audiodaten manuell in kleinere Blöcke unterteilen. In der Regel ist es jedoch effizienter und komfortabler, die Audiodaten in ein komprimiertes und verlustbehaftetes Format zu konvertieren. Die Komprimierung kann das mit einer einzigen Anforderung gesendete Datenvolumen maximieren. Insbesondere bei Audiodaten im WAF- oder FLAC-Format kann die Konvertierung in ein verlustbehaftetes Format einen deutlichen Unterschied machen.

• Weitere Informationen zu Audioformaten mit Komprimierung finden Sie unter Audioformate.
• Zusätzliche Angaben über die Auswirkungen der Komprimierung und über die Konvertierung Ihrer Audiodaten in ein Format, das die Komprimierung verwendet, enthalten die Abschnitte Datengrenzwerte und Komprimierung und Konvertierung von Audiodaten.
• Weitere Informationen zum Transkribieren des Audiosignals aus einer Multimedia-Datei, die Audio und Video enthält, finden Sie unter Sprache aus Videodateien transkribieren.

WebSocket-Schnittstelle verwenden

Die WebSocket-Schnittstelle bietet eine effiziente Implementierung über eine Vollduplexverbindung mit niedriger Latenzzeit und hohem Durchsatz. Alle Anforderungen und Antworten werden über dieselbe WebSocket-Verbindung gesendet.

Zur Verwendung der WebSocket-Schnittstelle müssen Sie zunächst mit der Methode /v1/recognize eine Verbindung zum Service herstellen. Hierbei geben Sie Parameter wie das Sprachmodell und alle angepassten Modelle an, die für die über die Verbindung gesendeten Anforderungen verwendet werden sollen. Anschließend registrieren Sie die Ereignislistener, um Antworten vom Service zu verarbeiten. Zum Ausgeben einer Anforderung senden Sie eine JSON-Textnachricht, die das Audioformat und alle weiteren Parameter enthält. Die Audiodaten übergeben Sie als binäre Nachricht (BLOB); anschließend senden Sie eine Textnachricht, um das Ende der Audiodaten zu signalisieren.

Das folgende Beispiel zeigt JavaScript-Code, der eine Verbindung aufbaut und die Textnachrichten sowie binären Nachrichten für eine Erkennungsanforderung sendet. Das einfache Beispiel enthält nicht den Code zum Definieren aller erforderlichen Ereignishandler für die Verbindung.

var access_token = {access_token};
var wsURI = '{ws_url}/v1/recognize'
  + '?access_token=' + access_token;
var websocket = new WebSocket(wsURI);

websocket.onopen = function(evt) { onOpen(evt) };

function onOpen(evt) {
  var message = {
    action: 'start',
    content-type: 'audio/flac'
  };
  websocket.send(JSON.stringify(message));
  websocket.send(blob);
  websocket.send(JSON.stringify({action: 'stop'}));
}

Synchrone HTTP-Schnittstelle verwenden

Die synchrone HTTP-Schnittstelle bietet das einfachste Verfahren für eine Erkennungsanforderung. Sie verwenden die Methode POST /v1/recognize, um eine Anforderung an den Service auszugeben. Zusammen mit dieser einzelnen Anforderung übergeben Sie die Audiodaten und alle Parameter. Das folgende curl-Beispiel zeigt eine einfache HTTP-Erkennungsanforderung:

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognize"

Asynchrone HTTP-Schnittstelle verwenden

Die asynchrone HTTP-Schnittstelle stellt eine nicht blockierende Schnittstelle für die Transkription von Audiodaten bereit. Sie können die Schnittstelle mit oder ohne vorherige Registrierung einer Callback-URL beim Service verwenden. Bei Registrierung einer Callback-URL sendet der Service Callback-Benachrichtigungen mit dem Jobstatus und den Erkennungsergebnissen. Die Schnittstelle verwendet auf einem vom Benutzer angegebenen geheimen Schlüssel basierende HMAC-SHA1-Signaturen, um Authentifizierung und Datenintegrität für seine Benachrichtigungen zu gewährleisten. Ohne eine Callback-URL müssen Sie den Jobstatus und die Ergebnisse beim Service abfragen. Bei beiden Ansätzen verwenden Sie die Methode POST /v1/recognitions, um eine Erkennungsanforderung auszugeben.

Das folgende curl-Beispiel zeigt eine einfache asynchrone HTTP-Erkennungsanforderung. Die Anforderung enthält keine Callback-URL; Sie müssen daher den Service abfragen, um den Jobstatus und die resultierende Transkription zu erhalten.

IBM Cloud

curl -X POST -u "apikey:{apikey}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"

IBM Cloud Pak for Data IBM Software Hub

curl -X POST \
--header "Authorization: Bearer {token}" \
--header "Content-Type: audio/flac" \
--data-binary @audio-file.flac \
"{url}/v1/recognitions"