Effettuare una richiesta di riconoscimento vocale

Per richiedere il riconoscimento vocale con il servizio IBM Watson® Speech to Text, devi fornire solo l'audio che deve essere trascritto. Il servizio offre le stesse funzionalità di trascrizione di base con ciascuna delle sue interfacce: l'interfaccia WebSocket, l'interfaccia HTTP sincrona e l'interfaccia HTTP asincrona.

Gli esempi che seguono mostrano le richieste di trascrizione di base, senza parametri opzionali, per ciascuna delle interfacce del servizio:

Gli esempi presentano un breve file FLAC denominato audio-file.flac.
Gli esempi utilizzano il modello di lingua predefinito, en-US_BroadbandModel. Per ulteriori informazioni, vedere Utilizzo del modello predefinito.

Comprendere i risultati del riconoscimento vocale descrive la risposta del servizio per questi esempi.

Requisiti di utilizzo

Quando effettui una richiesta di riconoscimento vocale, tieni conto dei seguenti requisiti di utilizzo di base:

I nomi di metodo sono sensibili a maiuscole/minuscole.
Le intestazioni di richiesta HTTP non sono sensibili a maiuscole/minuscole.
I parametri di query HTTP e WebSocket sono sensibili a maiuscole/minuscole.
I nomi di campo JSON sono sensibili a maiuscole/minuscole.
Tutto il contenuto di risposta JSON è nel set di caratteri UTF-8.
Nella documentazione vengono utilizzati parentesi graffe ({ }) per indicare valori variabili. Ometti le parentesi quadre quando fornisci valori variabili.

Tieni inoltre conto dei seguenti requisiti specifici per il servizio:

Devi specificare solo l'audio di input. Tutti gli altri parametri sono facoltativi.
Se necessario, assicurati di specificare il parametro " model " per indicare un modello adatto alla tua lingua e al tuo audio.
Se specifichi un campo JSON o un parametro di query non valido come parte dell'input, la risposta include un campo warnings che descrive l'argomento non valido. La richiesta ha esito positivo nonostante le eventuali avvertenze.

Invio di audio con una richiesta

L'audio che passi al servizio deve essere in uno dei formati supportati dal servizio. Per la maggior parte dei tipi di audio, il servizio può rilevare automaticamente il formato. Per alcuni tipi di audio, devi specificare il formato con Content-Type o un parametro equivalente. Per ulteriori informazioni, vedi Formati audio. (Per maggiore chiarezza, i seguenti esempi specificano il formato audio con tutte le richieste.)

Con le interfacce WebSocket e HTTP sincrona, puoi passare un massimo di 100 MB di dati audio con una singola richiesta. Con l'interfaccia HTTP asincrona, puoi passare un massimo di 1 GB di dati audio. Devi inviare almeno 100 byte di audio con qualsiasi richiesta.

Se riconosci grandi quantità di audio, puoi dividere manualmente l'audio in porzioni più piccole. Ma di solito è più efficiente e conveniente convertire l'audio in un formato compresso e con perdita. La compressione può massimizzare la quantità di dati che puoi inviare con una singola richiesta. Soprattutto se l'audio è in formato WAV o FLAC, convertirlo in un formato con perdita può fare una differenza considerevole.

Per ulteriori informazioni sui formati audio che utilizzano la compressione, vedere Formati audio.
Per ulteriori informazioni sugli effetti della compressione e sulla conversione dell'audio in un formato che la utilizza, vedi Limiti e compressione dei dati e Conversione audio.
Per ulteriori informazioni sulla trascrizione dell'audio da un file multimediale che contiene sia audio che video, vedi Trascrizione della voce da file video.

Utilizzo dell'interfaccia WebSocket

L'interfaccia WebSocket fornisce un'implementazione efficiente che offre bassa latenza e velocità effettiva elevata su una connessione full duplex. Tutte le richieste e le risposte vengono inviate tramite la stessa connessione WebSocket.

Per utilizzare l'interfaccia WebSocket, devi prima utilizzare il metodo /v1/recognize per stabilire una connessione con il servizio. Specifica i parametri come il modello di lingua e qualsiasi modello personalizzato da utilizzare per le richieste inviate tramite la connessione. Quindi, registra i listener di eventi per gestire le risposte fornite dal servizio. Per effettuare una richiesta, invia un messaggio di testo JSON che include il formato audio e qualsiasi parametro aggiuntivo. Passa l'audio come messaggio binario (blob), quindi invia un messaggio di testo per segnalare la fine dell'audio.

Il seguente esempio fornisce il codice JavaScript che stabilisce una connessione e invia i messaggi di testo e binari per una richiesta di riconoscimento. L'esempio di base non include il codice per definire tutti i gestori di eventi necessari per la connessione.

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

Utilizzo dell'interfaccia HTTP sincrona

L'interfaccia HTTP sincrona fornisce il modo più semplice per effettuare una richiesta di riconoscimento. Utilizza il metodo POST /v1/recognize per effettuare una richiesta al servizio. Passa l'audio e tutti i parametri con la singola richiesta. Il seguente esempio curl mostra una richiesta di riconoscimento HTTP di 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"

Utilizzo dell'interfaccia HTTP asincrona

L'interfaccia HTTP asincrona fornisce un'interfaccia non bloccante per la trascrizione dell'audio. Puoi utilizzare l'interfaccia con o senza la previa registrazione di un URL di callback con il servizio. Con un URL di callback, il servizio invia notifiche di callback con lo stato del lavoro e i risultati del riconoscimento. L'interfaccia utilizza le firme HMAC-SHA1 basate su un segreto specificato dall'utente per fornire l'autenticazione e l'integrità dei dati per le sue notifiche. Senza un URL di callback, devi eseguire il polling del servizio per ottenere lo stato del lavoro e i risultati. Con entrambi gli approcci, utilizzi il metodo POST /v1/recognitions per effettuare una richiesta di riconoscimento.

Il seguente esempio curl mostra una semplice richiesta di riconoscimento HTTP asincrona. La richiesta non include un URL di callback, quindi devi eseguire il polling del servizio per ottenere lo stato del lavoro e la trascrizione risultante.

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"