Cómo hacer una solicitud de reconocimiento de voz

Para solicitar un reconocimiento de voz con el servicio IBM Watson® Speech to Text, solo debe proporcionar el audio que se va a transcribir. El servicio ofrece las mismas funciones básicas de transcripción con cada una de sus interfaces: la interfaz WebSocket, la interfaz HTTP síncrona y la interfaz HTTP asíncrona.

Los ejemplos siguientes muestran las solicitudes de transcripción básicas, sin parámetros opcionales, para cada una de las interfaces del servicio:

Los ejemplos envían un breve archivo FLAC llamado audio-file.flac.
En los ejemplos se utiliza el modelo de lenguaje predeterminado, en-US_BroadbandModel. Para obtener más información, consulte Uso del modelo predeterminado.

Cómo comprender los resultados del reconocimiento de voz describe la respuesta del servicio para estos ejemplos.

Requisitos de uso

Tenga en cuenta los siguientes requisitos básicos sobre uso cuando realice una solicitud de reconocimiento de voz:

Los nombres de los métodos distinguen entre mayúsculas y minúsculas.
Las cabeceras de solicitudes HTTP no distinguen entre mayúsculas y minúsculas.
Los parámetros de consulta HTTP y WebSocket distinguen entre mayúsculas y minúsculas.
Los nombres de campos JSON distinguen entre mayúsculas y minúsculas.
Todo el contenido de la respuesta JSON está en el juego de caracteres UTF-8.
Las llaves ({ }) se utilizan en la documentación para indicar valores de variables. Omita las llaves al suministrar los valores de variables.

Tenga en cuenta también los siguientes requisitos específicos del servicio:

Solo es obligatorio especificar el audio de entrada. Todos los demás parámetros son opcionales.
Si es necesario, asegúrese de especificar el parámetro model para indicar un modelo que sea adecuado para el idioma y el audio.
Si especifica un parámetro de consulta o un campo JSON no válido como parte de la entrada, la respuesta incluye un campo warnings que describe el argumento no válido. La solicitud tiene éxito a pesar de los avisos.

Envío de audio con una solicitud

El audio que se pasa al servicio debe estar en uno de los formatos admitidos por el servicio. Para la mayoría de audio, el servicio puede detectar automáticamente el formato. Para algún audio, debe especificar el formato con el parámetro Content-Type o equivalente. Para obtener más información, consulte Formatos de audio. (Para que quede más claro, en los ejemplos siguientes se especifica el formato de audio con todas las solicitudes.)

Con las interfaces WebSocket y HTTP síncrona, puede pasar un máximo de 100 MB de datos de audio con una sola solicitud. Con la interfaz HTTP asíncrona, puede pasar un máximo de 1 GB de datos de audio. Debe enviar al menos 100 bytes de audio con cualquier solicitud.

Si va a reconocer una gran cantidad de audio, puede dividir manualmente el audio en porciones más pequeñas. Pero por lo general resulta más eficiente y conveniente convertir el audio a un formato comprimido con cierta pérdida de calidad (lossy). La compresión puede maximizar la cantidad de datos que puede enviar con una sola solicitud. Especialmente si el audio está en formato WAV o FLAC, convertirlo a un formato comprimido con pérdida puede suponer una diferencia significativa.

Para obtener más información sobre los formatos de audio que utilizan compresión, consulte Formatos de audio.
Para obtener más información sobre los efectos de la compresión y sobre la conversión de su audio a un formato que la utiliza, consulte los apartados sobre Límites de datos y compresión y Conversión de audio.
Para obtener más información sobre cómo transcribir el audio desde un archivo multimedia que contiene tanto audio como vídeo, consulte Transcripción de voz desde archivos de vídeo.

Utilización de la interfaz WebSocket

La interfaz WebSocket ofrece una implementación eficiente que proporciona una baja latencia y un alto rendimiento a través de una conexión dúplex. Todas las solicitudes y respuestas se envían a través de la misma conexión WebSocket.

Para utilizar la interfaz WebSocket, primero debe utilizar el método /v1/recognize para establecer una conexión con el servicio. Debe especificar los parámetros, como el modelo de lenguaje y cualquier modelo personalizado que se vaya a utilizar para solicitudes enviadas a través de la conexión. Luego debe registrar escuchas de sucesos para gestionar las respuestas procedentes del servicio. Para realizar una solicitud, envíe un mensaje de texto JSON que incluya el formato de audio y los parámetros adicionales. Pase el audio como un mensaje binario (blob) y luego envíe un mensaje de texto para indicar el final del audio.

En el ejemplo siguiente se proporciona código JavaScript que establece una conexión y envía los mensajes binario y de texto para una solicitud de reconocimiento. El ejemplo básico no incluye el código para definir todos los manejadores de sucesos necesarios para la conexión.

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'}));
}

Utilización de la interfaz HTTP síncrona

La interfaz HTTP síncrona ofrece la forma más sencilla de realizar una solicitud de reconocimiento. Utilice el método POST /v1/recognize para realizar una solicitud al servicio. Pase el audio y todos los parámetros en una sola solicitud. En el siguiente ejemplo de curl se muestra una solicitud básica de reconocimiento HTTP:

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"

Utilización de la interfaz HTTP asíncrona

La interfaz HTTP asíncrona ofrece interfaz que no es de bloqueo para transcribir el audio. Puede utilizar la interfaz registrando o no antes un URL de devolución de llamada con el servicio. Con un URL de devolución de llamada, el servicio envía notificaciones de devolución de llamada con el estado del trabajo y los resultados del reconocimiento. La interfaz utiliza firmas HMAC-SHA1 basadas en un secreto especificado por el usuario para proporcionar autenticación e integridad de los datos para sus notificaciones. Sin el URL de devolución de llamada, debe sondear el servicio para ver el estado del trabajo y los resultados. Con cualquiera de los enfoques, debe utilizar el método POST /v1/recognitions para realizar una solicitud de reconocimiento.

En el siguiente ejemplo de curl se muestra una solicitud sencilla de reconocimiento HTTP asíncrona. La solicitud no incluye un URL de devolución de llamada, por lo que debe sondear el servicio para obtener el estado de trabajo y la transcripción resultante.

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"