Faire une demande de reconnaissance vocale

Pour effectuer une demande de reconnaissance vocale avec le service IBM Watson® Speech to Text, il vous suffit de fournir les données audio à transcrire. Le service offre les mêmes fonctions de transcription de base avec chacune de ses interfaces : l'interface WebSocket, l'interface HTTP synchrone et l'interface HTTP asynchrone.

Les exemples suivants montrent des requêtes de transcription de base, sans paramètres optionnels, pour chacune des interfaces du service :

Les exemples soumettent un bref fichier FLAC nommé audio-file.flac.
Les exemples utilisent le modèle de langue par défaut, en-US_BroadbandModel. Pour plus d'informations, voir Utilisation du modèle par défaut.

Comprendre les résultats de la reconnaissance vocale décrit la réponse du service à ces exemples.

Exigences d'utilisation

Tenez compte des exigences d'utilisation de base lorsque vous effectuez une demande de reconnaissance vocale :

Les noms de méthode sont sensibles à la casse.
Les en-têtes de demande HTTP ne sont pas sensibles à la casse.
Les paramètres de requête HTTP et WebSocket sont sensibles à la casse.
Les noms de zone JSON sont sensibles à la casse.
Tout le contenu des réponses JSON utilise le jeu de caractères UTF-8.
Les accolades ({ }) sont utilisées dans la documentation pour indiquer des valeurs de variable. Omettez les accolades lors de la fourniture de valeurs de variable.

Tenez compte également des exigences suivantes spécifiques au service :

Vous ne devez spécifier que l'entrée audio. Tous les autres paramètres sont facultatifs.
Si nécessaire, assurez-vous de spécifier le paramètre model pour indiquer un modèle approprié pour votre langue et votre audio.
Si vous spécifiez un paramètre de requête ou une zone JSON non valide dans l'entrée, la réponse comprend une zone warnings pour décrire l'argument non valide. La demande aboutit malgré les avertissements de ce type.

Envoi de données audio avec une demande

Les données audio que vous transmettez au service doivent être dans l'un des formats pris en charge par le service. Pour la plupart des données audio, le service peut détecter automatiquement le format. Pour d'autres, vous devez spécifier le format avec le paramètre Content-Type ou un paramètre équivalent. Pour plus d'informations, voir Formats audio. (Pour que ce soit plus clair, les exemples suivants indiquent le format audio avec toutes les demandes.)

Avec les interfaces WebSocket et HTTP synchrone, vous pouvez transmettre jusqu'à 100 Mo de données audio maximum avec une seule demande. Avec l'interface HTTP asynchrone, vous pouvez transmettre jusqu'à 1 Go de données audio maximum. Vous devez envoyer au moins 100 octets de données audio avec une demande.

Si vous effectuez la reconnaissance de grandes quantités de données audio, vous pouvez diviser manuellement ces données en blocs de plus petite taille. Mais en général, il est plus efficace et pratique de convertir les données audio dans un format compressé avec perte. La compression peut maximiser la quantité de données que vous pouvez envoyer avec une seule demande. S'il s'agit notamment de données audio au format WAV ou FLAC, la conversion au format avec perte peut constituer une différence appréciable.

Pour plus d'informations sur les formats audio qui utilisent la compression, voir Formats audio.
Pour plus d'informations sur les effets de la compression et sur la conversion de vos données audio en format avec compression, voir Limites et compression de données et Conversion audio.
Pour plus d'informations sur la transcription des données audio à partir d'un fichier multimédia contenant à la fois des données audio et des données vidéo, voir Transcription de la parole à partir de fichiers vidéo.

Utilisation de l'interface WebSocket

L'interface WebSocket offre une implémentation efficace, à faible temps d'attente et à haut débit via une connexion en duplex intégral. Toutes les demandes et les réponses sont envoyées via la même connexion WebSocket.

Pour utiliser l'interface WebSocket, vous devez d'abord utiliser la méthode /v1/recognize pour établir une connexion avec le service. Vous spécifiez les paramètres, tels que le modèle de langue et tout modèle personnalisé à utiliser pour les demandes envoyées via la connexion. Vous enregistrez ensuite les programmes d'écoute pour traiter les réponses renvoyées par le service. Pour effectuer une demande, vous envoyez un message texte JSON incluant le format audio et des paramètres supplémentaires, le cas échéant. Vous transmettez les données audio sous forme de message binaire (blob), puis vous envoyez un message texte pour signaler la fin des données audio.

L'exemple suivant fournit un code JavaScript qui établit une connexion et envoie les messages texte et les messages binaires pour une demande de reconnaissance. L'exemple de base n'inclut pas le code permettant de définir tous les gestionnaires d'événements nécessaires pour la connexion.

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

Utilisation de l'interface HTTP synchrone

L'interface HTTP synchrone constitue le moyen le plus simple d'effectuer une demande de reconnaissance. Vous utilisez la méthode POST /v1/recognize pour effectuer une demande auprès du service. Vous transmettez les données audio et tous les paramètres avec cette demande unique. L'exemple de commande curl suivant présente une demande de reconnaissance HTTP de base :

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"

Utilisation de l'interface HTTP asynchrone

L'interface HTTP asynchrone fournit une interface non bloquante pour la transcription audio. Vous pouvez utiliser l'interface avec ou sans enregistrement préalable d'une URL de rappel avec le service. Avec une URL de rappel, le service envoie des notifications de rappel comprenant le statut du travail et les résultats de reconnaissance. L'interface utilise des signatures HMAC-SHA1 basées sur une valeur secrète spécifiée par l'utilisateur pour permettre l'authentification et assurer l'intégrité des données de ses notifications. Sans URL de rappel, vous devez interroger le service pour connaître le statut du travail et obtenir les résultats. Avec l'une ou l'autre de ces approches, vous utilisez la méthode POST /v1/recognitions pour effectuer une demande de reconnaissance.

L'exemple de commande curl suivant présente une demande de reconnaissance HTTP asynchrone simple. La demande ne contenant pas d'URL de rappel, vous devez interroger le service pour obtenir le statut du travail et la transcription qui en résulte.

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"