Abrir una conexión

Para abrir una conexión con el servicio se debe hacer una llamada al método /v1/synthesize a través del protocolo WebSocket Secure (WSS). El método está disponible en el punto final siguiente:

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

donde {location} indica el lugar en el que se aloja la aplicación:

• us-south para Dallas
• us-east para Washington, DC
• eu-de para Frankfurt
• au-syd para Sídney
• jp-tok para Tokio
• eu-gb para Londres
• kr-seo para Seúl

Y {instance_id} es el identificador exclusivo de la instancia de servicio.

Los ejemplos de la documentación abrevian wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} como {ws_url}. Por lo tanto, todos los ejemplos de WebSocket invocan al método como {ws_url}/v1/synthesize.

Un cliente WebSocket llama al método /v1/synthesize con los siguientes parámetros de consulta para establecer una conexión autenticada con el servicio:

access_token (serie obligatoria)

Pase una señal de acceso válida para autenticarse con el servicio. Debe utilizar la señal de acceso antes de que caduque.

• IBM Cloud Pasar un token de acceso de gestión de identidades y accesos ( Identity and Access Management, IAM) para autenticarse en el servicio. Se pasa una señal de acceso de IAM en lugar de pasar una clave de API con la llamada. Para obtener más información, consulte Autenticación en IBM Cloud.
• IBM Cloud Pak for Data pase un token de acceso como lo haría con el encabezado "xml-ph-0000@deepl.internal" de una solicitud "xml-ph-0001@deepl.internal" IBM Software Hub Pase un token de acceso como lo haría con el encabezado " Authorization " de una solicitud " HTTP ". Para obtener más información, consulte Autenticación en IBM Cloud Pak for Data.

voice (serie opcional)

Especifica la voz en que se debe leer el texto en el audio. Utilice el método /v1/voices para obtener la lista actual de voces soportadas. Omita este parámetro para utilizar la voz predeterminada. Para más información, consulte Idiomas y voces y Utilizar la voz predeterminada.

customization_id (serie opcional)

Especifica el identificador exclusivo global (GUID) para un modelo personalizado que se debe utilizar para la síntesis. Un modelo personalizado especificado debe coincidir con el idioma de la voz que se utiliza para la síntesis. Si incluye un ID de personalización, debe realizar la solicitud con las credenciales para la instancia del servicio que posee el modelo personalizado. Omita el parámetro para utilizar la voz especificada sin personalización. Para obtener más información, consulte Comprender la personalización.

rate_percentage (opcional integer)

Especifica la frecuencia de habla global para toda la solicitud de síntesis. La velocidad de habla es la velocidad a la que el servicio pronuncia el texto que sintetiza en voz. Una velocidad más alta hace que el texto se pronuncie más rápidamente; una velocidad más baja hace que el texto se pronuncie más lentamente. El parámetro cambia la tarifa por defecto por voz para toda una solicitud. Para más información, consulte Modificar la velocidad de conversación.

pitch_percentage (opcional integer)

Especifica el tono de voz global para toda la solicitud de síntesis. El tono del habla representa el tono del habla que sintetiza el servicio. Representa lo alto o bajo que percibe el oyente el tono de la voz. Un tono más agudo da lugar a un discurso en el que se habla con un tono más alto; un tono más bajo da lugar a un discurso en el que se habla con un tono más bajo. El parámetro cambia el tono predeterminado por voz para toda una petición. Para más información, consulte Modificar el tono de voz.

spell_out_mode (serie opcional)

Para las voces en alemán, especifica cómo deben escribirse los caracteres individuales de una cadena. Por defecto, el servicio deletrea los caracteres individuales a la misma velocidad a la que sintetiza el texto de una lengua. Puede utilizar este parámetro para indicar al servicio que escriba caracteres individuales más lentamente, en grupos de uno singles), dos pairs) o tres triples). Para obtener más información, consulte Especificar cómo se escriben las cadenas.

x-watson-metadata (serie opcional)

Asocia un ID de cliente con los datos que se pasan a través de la conexión. El parámetro acepta el argumento customer_id={id}, donde id es una serie aleatoria o genérica para asociar a los datos. Debe codificar en URL el argumento para el parámetro, por ejemplo customer_id%3dmy_customer_ID. De forma predeterminada, no hay ningún ID de cliente asociado a los datos. Para obtener más información, consulte Seguridad de la información.

x-watson-learning-opt-out (booleano opcional)

IBM Cloud Indica si el servicio registra las solicitudes y los resultados que se envían a través de la conexión. Para evitar que IBM acceda a sus datos para mejoras de servicio generales, especifique true en el parámetro. La opción Renuncia indica a IBM que no grabe en disco los datos de usuario (texto o audio) de su solicitud. También puede excluirse a nivel de cuenta. Para obtener más información, consulte Registro de solicitudes.

El siguiente fragmento de código JavaScript abre una conexión con el servicio. La llamada al método /v1/synthesize pasa los parámetros de consulta voice y access_token, el primero para indicar al servicio que debe utilizar la voz de Allison en inglés de Estados Unidos. Una vez establecida la conexión, se definen los escuchas de sucesos (onOpen(), onClose(), etc.) para responder a los sucesos del servicio.

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

Enviar texto de entrada

Para sintetizar texto, el cliente pasa un mensaje de texto JSON simple al servicio con los parámetros siguientes:

text (serie obligatoria)

Proporciona el texto a sintetizar. El cliente puede pasar texto sin formato o texto anotado con SSML (Speech Synthesis Markup Language). El cliente puede pasar un máximo de 5 KB de texto de entrada con la solicitud. Este límite incluye cualquier SSML especificado. Para obtener más información, consulte Especificar texto de entrada y las secciones siguientes. (La entrada SSML también puede incluir el elemento <mark>. Para obtener más información, consulte Especificar una marca SSML).

accept (serie obligatoria)

Especifica el formato solicitado (tipo MIME) del audio. Utilice */* para solicitar el formato de audio predeterminado, audio/ogg;codecs=opus. Para obtener más información, consulte Utilización de formatos de audio.

El formato de audio Ogg no es compatible con el navegador Safari. Si utiliza el servicio Text to Speech con el navegador Safari, deberá especificar un formato diferente en el que desea que el servicio devuelva el audio.

timings (serie opcional[ ])

Especifica que el servicio debe devolver información de temporización de palabras para todas las series del texto de entrada. El servicio devuelve el momento de inicio y finalización de cada señal de entrada. Especifique words como único elemento de la matriz para solicitar temporizaciones de palabras. Especifique una matriz vacía o bien omita el parámetro para no recibir temporizaciones de palabras. Para más información, consulte Generación de tiempos de palabra. No se admite para el texto de entrada en japonés.

El siguiente fragmento de código JavaScript pasa un mensaje "Hello world" simple como texto de entrada y solicita el formato predeterminado para el audio. Las llamadas se incluyen en la función onOpen() que se ha definido para el cliente para asegurarse de que se envían sólo después de establecer la conexión.

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

El servicio responde a este mensaje enviando un mensaje de texto que confirma el formato de la respuesta de audio. La siguiente respuesta confirma el formato de audio predeterminado.

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

Recibir una respuesta

Una vez que ha confirmado el formato de audio, el servicio envía el audio sintetizado como una corriente binaria de datos en el formato indicado. En el caso de formatos de audio que incluyen una cabecera (por ejemplo, audio/wav y audio/ogg), el servicio devuelve la cabecera antes de enviar los datos de audio. La cabecera puede abarcar varias respuestas binarias. Para todos los formatos de audio, el cliente tiene que añadir todas las respuestas binarias del servicio para ensamblar la respuesta de audio completa.

Además de enviar un mensaje de texto que confirme el formato de audio solicitado, el servicio también puede enviar mensajes de texto con avisos o errores. El servicio también envía uno o varios mensajes de texto que incluyen información de temporización si

• El texto de entrada incluye uno o más elementos SSML <mark>.
• Se ha especificado el parámetro timings en la solicitud.

El cliente puede manejar mensajes de texto respondiendo a los mismos, visualizándolos o capturándolos para que los utilice la aplicación (por ejemplo, si contienen ubicaciones de marcas).

Cuando termina de sintetizar el texto de entrada y de enviar todos los mensajes binarios y de texto, el servicio cierra automáticamente la conexión de WebSocket. La siguiente función onMessage() simple añade mensajes binarios y de texto que se reciben del servicio a las variables adecuadas en función de su tipo. Cuando se ejecuta la función onClose(), ya se ha recibido toda la secuencia de audio y el servicio no envía más mensajes de texto o binarios.

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.
}

Códigos de retorno de WebSocket

El servicio puede enviar los siguientes códigos de retorno al cliente a través de la conexión de WebSocket:

• 1000 indica el cierre normal de la conexión, lo que significa que la finalidad para la que se ha establecido la conexión se ha cumplido.
• 1002 indica que el servicio cierra la conexión debido a un error de protocolo.
• 1006 indica que la conexión se ha cerrado anormalmente.
• 1009 indica que el tamaño de trama ha sobrepasado el límite de 4 MB.
• 1011 indica que el servicio está terminando la conexión porque ha encontrado una condición inesperada que le impide cumplir la solicitud, como por ejemplo un argumento no válido. El código de retorno también puede indicar que el texto de entrada era demasiado grande.

Si el socket se cierra con un error, el servicio envía al cliente un mensaje informativo con el formato {"error": "Specific error message"} antes de cerrarse. El servicio también puede enviar mensajes de aviso no muy graves para parámetros desconocidos. Para obtener más información sobre los códigos de respuesta de WebSocket, consulte la Solicitud de comentarios(RFC)6455 del Grupo de Trabajo en Ingeniería de Internet (IETF).

Las implementaciones de WebSocket de los SDK pueden devolver códigos de respuesta diferentes o adicionales.

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