Ouvrir une connexion

Vous appelez la méthode /v1/synthesize via le protocole WebSocket Secure (WSS) pour ouvrir une connexion au service. La méthode est disponible sur le noeud final suivant :

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

Où {location} indique l'emplacement où votre application est hébergée :

• us-south pour Dallas
• us-east pour Washington, DC
• eu-de pour Francfort
• au-syd pour Sydney
• jp-tok pour Tokyo
• eu-gb pour Londres
• kr-seo pour Séoul

Et {instance_id} est l'identificateur unique de l'instance de service.

Dans les exemples de la documentation wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} est abrégé {ws_url}. Par conséquent, tous les exemples WebSocket appellent la méthode {ws_url}/v1/synthesize.

Un client WebSocket appelle la méthode /v1/synthesize avec les paramètres de requête suivants pour établir une connexion authentifiée avec le service :

access_token (chaîneobligatoire)

Transmettez un jeton d'accès valide pour vous authentifier auprès du service. Vous devez utiliser le jeton d'accès avant son expiration.

• IBM Cloud Transmettre un jeton d'accès IAM ( Identity and Access Management ) pour s'authentifier auprès du service. Vous transmettez un jeton d'accès IAM au lieu de transmettre une clé d'API avec l'appel. Pour plus d'informations, voir Authentification dans IBM Cloud.
• IBM Cloud Pak for Data Passez un jeton d'accès comme vous le feriez avec l'en-tête xml-ph-0000@deepl.internal d'une requête xml-ph-0001@deepl.internal IBM Software Hub Passez un jeton d'accès comme vous le feriez avec l'en-tête " Authorization " d'une requête " HTTP ". Pour plus d'informations, consultez Authentification sur IBM Cloud Pak for Data.

voice (chaînefacultative )

Spécifie la voix dans laquelle le texte doit être prononcé en audio. Utilisez la méthode /v1/voices pour obtenir la liste actuelle des voix prises en charge. Omettez le paramètre pour utiliser la voix par défaut. Pour plus d'informations, voir Langues et voix et Utiliser la voix par défaut.

customization_id (chaînefacultative )

Indique l'identificateur global unique (GUID) d'un modèle personnalisé à utiliser pour la synthèse. Un modèle personnalisé spécifié doit correspondre à la langue de la voix utilisée pour la synthèse. Si vous incluez un ID de personnalisation, vous devez faire la demande avec les données d'identification de l'instance du service propriétaire du modèle personnalisé. Omettez le paramètre pour utiliser la voix spécifiée sans personnalisation. Pour plus d'informations, voir Compréhension de la personnalisation.

rate_percentage (facultatif integer)

Spécifie le débit de parole global pour l'ensemble de la demande de synthèse. La vitesse d'élocution est la vitesse à laquelle le service prononce le texte qu'il synthétise en parole. Un taux plus élevé signifie que le texte est prononcé plus rapidement ; un taux plus bas signifie que le texte est prononcé plus lentement. Ce paramètre modifie le taux par défaut par voix pour l'ensemble d'une requête. Pour plus d'informations, voir Modifier le débit de parole.

pitch_percentage (facultatif integer)

Spécifie la hauteur de voix globale pour l'ensemble de la demande de synthèse. La hauteur de la voix représente le ton de la parole que le service synthétise. Il représente le degré d'intensité du ton de la voix perçu par l'auditeur. Une hauteur de ton plus élevée se traduit par un discours prononcé sur un ton plus aigu ; une hauteur de ton plus basse se traduit par un discours prononcé sur un ton plus grave. Ce paramètre modifie la hauteur de ton par voix pour l'ensemble de la requête. Pour plus d'informations, voir Modifier la hauteur de la voix.

spell_out_mode (chaînefacultative )

Pour les voix allemandes, spécifie comment les caractères individuels d'une chaîne doivent être épelés. Par défaut, le service épelle les caractères individuels à la même vitesse que celle à laquelle il synthétise le texte d'une langue. Vous pouvez utiliser ce paramètre pour demander au service d'épeler les caractères individuels plus lentement, par groupes de un singles, deux pairs) ou trois triples. Pour plus d'informations, voir Spécification de l'épellation des chaînes de caractères.

x-watson-metadata (chaînefacultative )

Associe un ID client aux données transmises via la connexion. Ce paramètre accepte l'argument customer_id={id}, où id représente une chaîne aléatoire ou générique à associer aux données. Vous devez coder l'argument de ce paramètre en codage URL, par exemple, customer_id%3dmy_customer_ID. Par défaut, aucun ID client n'est associé aux données. Pour plus d'informations, voir Sécurité des informations.

x-watson-learning-opt-out (facultatif booléen)

IBM Cloud Indique si le service enregistre les demandes et les résultats envoyés via la connexion. Pour empêcher IBM d’accéder à vos données afin d’améliorer les services généraux, indiquez true pour le paramètre. L'option d'exclusion demande à IBM de ne pas écrire sur disque les données utilisateur (texte ou audio) pour votre demande. Vous pouvez également vous désinscrire au niveau du compte. Pour plus d'informations, voir Journalisation des demandes.

Le fragment de code JavaScript suivant ouvre une connexion avec le service. L'appel à la méthode /v1/synthesize transmet les paramètres de requête voice et access_token, le premier permettant au service d'utiliser la voix en anglais américain Allison. Une fois la connexion établie, les programmes d'écoute d'événement (onOpen(), onClose(), etc.) sont définis pour répondre aux événements du service.

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

Envoyer un texte de saisie

Pour synthétiser du texte, le client transmet un message de texte JSON simple au service avec les paramètres suivants :

text (chaîneobligatoire)

Fournit le texte à synthétiser. Le client peut transmettre du texte brut ou du texte annoté avec le langage SSML (Speech Synthesis Markup Language). Le client peut transmettre un maximum de 5 Ko de texte en entrée avec la demande. La limite inclut tout le texte SSML que vous spécifiez. Pour plus d'informations, voir Spécification de texte en entrée et les sections qui suivent cette rubrique. (L'entrée SSML peut également inclure l'élément <mark>. Pour plus d'informations, voir Spécification d'une marque SSML.)

accept (chaîneobligatoire)

Spécifie le format demandé (type MIME) de l'audio. Utilisez */* pour demander le format audio par défaut, audio/ogg;codecs=opus. Pour plus d'informations, voir Utilisation des formats audio.

Le format audio Ogg n'est pas pris en charge par le navigateur Safari. Si vous utilisez le service Text to Speech avec le navigateur Safari, vous devez spécifier un format différent dans lequel vous souhaitez que le service renvoie l'audio.

timings (chaînefacultative[ ])

Spécifie que le service doit renvoyer des informations de minutage des mots pour toutes les chaînes du texte en entrée. Le service renvoie le temps de début et de fin de chaque jeton de l'entrée. Spécifiez words en tant qu'élément isolé du tableau pour demander le minutage des mots. Spécifiez un tableau vide ou omettez le paramètre pour ne recevoir aucun minutage de mot. Pour plus d'informations, voir Générer des temporisations de mots. Non pris en charge pour le texte d'entrée japonais.

Le fragment de code JavaScript suivant transmet un simple message "Hello world" en tant que texte d'entrée et demande le format audio par défaut. Les appels sont inclus dans la fonction onOpen() définie pour le client, qu'ils ne soient envoyés qu'une fois la connexion établie.

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

Le service répond à ce message en envoyant un message texte confirmant le format de la réponse audio. La réponse suivante confirme le format audio par défaut.

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

Recevoir une réponse

Après avoir confirmé le format audio, le service envoie le son synthétisé sous forme de flux binaire de données au format indiqué. Pour les formats audio incluant un en-tête (par exemple, audio/wav et audio/ogg), le service renvoie l'en-tête avant d'envoyer les données audio. L'en-tête peut couvrir plusieurs réponses binaires. Pour tous les formats audio, le client doit ajouter toutes les réponses binaires émanant du service pour assembler la réponse audio complète.

Outre un message texte qui confirme le format audio demandé, le service peut également envoyer des messages texte avec des avertissements ou des erreurs. Le service envoie également un ou plusieurs messages texte incluant des informations de minutage si

• Le texte d'entrée inclut un ou plusieurs éléments SSML <mark>.
• Vous spécifiez le paramètre timings avec la demande.

Le client peut gérer les messages texte en y répondant, en les affichant ou en les capturant pour une utilisation par l'application (par exemple, s'ils contiennent des emplacements de marque).

Une fois la synthèse du texte en entrée et l'envoi de tous les messages texte et binaires terminés, le service ferme automatiquement la connexion WebSocket. La fonction onMessage() simple suivante ajoute le texte et les messages binaires reçus du service aux variables appropriées en fonction de leur type. Lorsque la fonction onClose() s'exécute, tout le flux audio a été reçu et le service n'envoie plus aucun autre message texte ou binaire.

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

Codes de retour WebSocket

Le service peut envoyer les codes de retour suivants au client via la connexion WebSocket :

• 1000 indique la fermeture normale de la connexion, ce qui signifie que le but recherché en établissant cette connexion a été atteint.
• 1002 indique que le service ferme la connexion en raison d'une erreur de protocole.
• 1006 indique que la connexion ne s'est pas fermée normalement.
• 1009 indique que la taille de trame dépasse la limite de 4 Mo.
• 1011 indique que le service met fin à la connexion car il a rencontré une condition inattendue l'empêchant de répondre à la demande, par exemple un argument non valide. Le code retour peut également indiquer que le texte en entrée était trop volumineux.

Si le socket se ferme avec une erreur, le service envoie au client un message informatif du type {"error": "Specific error message"} avant de se fermer. Le service peut également envoyer des messages d'avertissement non fatals pour des paramètres inconnus. Pour plus d'informations sur les codes de retour d' WebSocket, consultez la demande de commentaires(RFC)6455 de l'Internet Engineering Task Force (IETF).

Les implémentations de WebSocket des kits SDK peuvent renvoyer des codes de réponse différents ou supplémentaires.

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