Apri una connessione

Richiama il metodo /v1/synthesize sul protocollo WSS (WebSocket Secure) per aprire una connessione al servizio. Il metodo è disponibile nel seguente endpoint:

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

dove {location} indica dove viene ospitata la tua applicazione:

• us-south per Dallas
• us-east per Washington, DC
• eu-de per Francoforte
• au-syd per Sydney
• jp-tok per Tokyo
• eu-gb per Londra
• kr-seo per Seul

E {instance_id} è l'identificativo univoco dell'istanza del servizio.

Gli esempi nella documentazione abbreviano wss://api.{location}.text-to-speech.watson.cloud.ibm.com/instances/{instance_id} in {ws_url}. Pertanto, tutti gli esempi WebSocket richiamano il metodo come {ws_url}/v1/synthesize.

Un client di WebSocket chiama il metodo /v1/synthesize con i seguenti parametri di query per stabilire una connessione autenticata con il servizio:

access_token (richiesto string)

Passare un token di accesso valido per autenticarsi con il servizio. Devi utilizzare il token di accesso prima che scada.

• IBM Cloud Passare un token di accesso a Identity and Access Management (IAM) per autenticarsi con il servizio. Passa un token di accesso IAM invece di passare una chiave API con la chiamata. Per ulteriori informazioni, vedere Autenticazione su IBM Cloud.
• IBM Cloud Pak for Data passare un token di accesso come si farebbe con l'intestazione "xml-ph-0000@deepl.internal" di una richiesta "xml-ph-0001@deepl.internal" IBM Software Hub Passa un token di accesso come faresti con l'intestazione " Authorization " di una richiesta " HTTP ". Per ulteriori informazioni, vedere Autenticazione su IBM Cloud Pak for Data.

voice (opzionale string)

Specifica la voce in cui deve essere pronunciato il testo nell'audio. Utilizzare il metodo /v1/voices per ottenere l'elenco aggiornato delle voci supportate. Ometti il parametro per utilizzare la voce predefinita. Per ulteriori informazioni, vedere Lingue e voci e Uso della voce predefinita.

customization_id (opzionale string)

Specifica l'identificatore univoco globale (GUID) per un modello personalizzato da utilizzare per la sintesi. Un modello personalizzato specifico deve corrispondere alla lingua della voce utilizzata per la sintesi. Se includi un ID di personalizzazione, devi effettuare la richiesta con le credenziali per l'istanza del servizio proprietaria del modello personalizzato. Ometti il parametro per utilizzare la voce specificata senza alcuna personalizzazione. Per ulteriori informazioni, vedi Informazioni sulla personalizzazione.

rate_percentage (opzionale integer)

Specifica il tasso di conversazione globale per l'intera richiesta di sintesi. La velocità di riproduzione è la velocità con cui il servizio pronuncia il testo che sintetizza nel parlato. Una velocità maggiore fa sì che il testo venga pronunciato più velocemente; una velocità minore fa sì che il testo venga pronunciato più lentamente. Il parametro modifica la velocità predefinita per voce per un'intera richiesta. Per ulteriori informazioni, vedere Modifica della velocità di parola.

pitch_percentage (opzionale integer)

Specifica il tono di voce globale per l'intera richiesta di sintesi. Il tono di voce rappresenta il tono del discorso che il servizio sintetizza. Rappresenta il tono alto o basso della voce percepito dall'ascoltatore. Un'intonazione più alta si traduce in un discorso che viene pronunciato con un tono più alto; un'intonazione più bassa si traduce in un discorso che viene pronunciato con un tono più basso. Il parametro modifica l'intonazione predefinita per voce per un'intera richiesta. Per ulteriori informazioni, vedere Modifica dell'intonazione del parlato.

spell_out_mode (opzionale string)

Per le voci tedesche, specifica come devono essere scritti i singoli caratteri di una stringa. Per impostazione predefinita, il servizio scrive i singoli caratteri alla stessa velocità con cui sintetizza il testo per una lingua. È possibile utilizzare il parametro per indicare al servizio di scrivere i singoli caratteri più lentamente, a gruppi di uno singles), due pairs) o tre triples). Per ulteriori informazioni, consultare la sezione Specificare l'ortografia delle stringhe.

x-watson-metadata (opzionale string)

Associa un ID cliente ai dati che vengono passati tramite la connessione. Il parametro accetta l'argomento customer_id={id}, dove id è una stringa casuale o generica che deve essere associata ai dati. Devi codificare in URL l'argomento nel parametro, ad esempio, customer_id%3dmy_customer_ID. Per impostazione predefinita, nessun ID cliente è associato ai dati. Per ulteriori informazioni, vedi Sicurezza delle informazioni.

x-watson-learning-opt-out (opzionale boolean)

IBM Cloud Indica se il servizio registra le richieste e i risultati inviati tramite la connessione. Per impedire che IBM acceda ai tuoi dati per miglioramenti del servizio generali, specifica true per il parametro. L'opt-out indirizza IBM a scrivere su disco no i dati dell'utente (testo o audio) per la richiesta dell'utente. È inoltre possibile rinunciare al servizio a livello di account. Per ulteriori informazioni, vedi Registrazione delle richieste.

Il seguente frammento di codice JavaScript apre una connessione con il servizio. La chiamata al metodo /v1/synthesize passa i parametri di query voice e access_token, i primi a indirizzare il servizio a utilizzare la voce in inglese (Stati Uniti) Allison. Una volta stabilita la connessione, gli ascoltatori di eventi (onOpen(), onClose() e così via) vengono definiti per rispondere agli eventi dal servizio.

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

Invia il testo di input

Per sintetizzare il testo, il cliente invia al servizio un semplice messaggio di testo JSON con i seguenti parametri:

text (richiesto string)

Fornisce il testo da sintetizzare. Il client può passare il testo semplice o il testo annotato con SSML (Speech Synthesis Markup Language). Il client può passare massimo 5 KB di testo di input con la richiesta. Il limite include qualsiasi SSML tu specifichi. Per ulteriori informazioni, vedi Specifica del testo di input e le sezioni che seguono. (L'input SSML può includere anche l'elemento " <mark> ". Per ulteriori informazioni, vedi Specifica di un contrassegno SSML.)

accept (richiesto string)

Specifica il formato richiesto (tipo MIME) dell'audio. Utilizzare */* per richiedere il formato audio predefinito, audio/ogg;codecs=opus. Per ulteriori informazioni, vedere Utilizzo dei formati audio.

Il formato audio Ogg non è supportato dal browser Safari. Se si utilizza il servizio Text to Speech con il browser Safari, è necessario specificare un formato diverso in cui si desidera che il servizio restituisca l'audio.

timings (opzionale string[ ])

Specifica che il servizio deve restituire le informazioni di temporizzazione delle parole per tutte le stringhe del testo di input. Il servizio restituisce il tempo di inizio e di fine di ogni token nell'input. Specificare " words " come unico elemento dell'array per richiedere i tempi delle parole. Specifica un array vuoto oppure ometti il parametro per non ricevere alcuna temporizzazione delle parole. Per ulteriori informazioni, vedere Generazione delle temporizzazioni delle parole. Non supportato per testo di input giapponese.

Il seguente frammento di codice JavaScript passa un semplice messaggio "Hello world" come testo di input e richiede il formato predefinito per l'audio. Le chiamate sono incluse nella funzione " onOpen() " (Chiamata in attesa) che viene definita per il cliente per garantire che vengano inviate solo dopo che la connessione è stata stabilita.

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

Il servizio risponde a questo messaggio inviando un messaggio di testo che conferma il formato della risposta audio. La seguente risposta conferma il formato audio predefinito.

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

Ricevi una risposta

Una volta confermato il formato audio, il servizio invia l'audio sintetizzato come un flusso binario di dati nel formato indicato. Per i formati audio che includono un'intestazione (ad esempio, audio/wav e audio/ogg), il servizio restituisce l'intestazione prima di inviare i dati audio. L'intestazione può estendersi a più risposte binarie. Per tutti i formati audio, il client deve accodare tutte le risposte binarie del servizio per assemblare la risposta audio completa.

Oltre a inviare un messaggio di testo che conferma il formato audio richiesto, il servizio può anche inviare messaggi di testo con avvertenze o errori. Il servizio invia anche uno o più messaggi di testo che includono le informazioni di temporizzazione se

• Il testo di input include uno o più elementi SSML ( <mark> ).
• Specifichi il parametro timings con la richiesta.

Il client può gestire i messaggi di testo rispondendo ad essi, visualizzandoli o acquisendoli per essere utilizzati dall'applicazione (ad esempio, se contengono posizioni di contrassegno).

Quando termina di sintetizzare il testo di input e di inviare tutti i messaggi binari e di testo, il servizio chiude automaticamente la connessione WebSocket. La seguente semplice funzione di " onMessage() " aggiunge i messaggi di testo e binari ricevuti dal servizio alle variabili appropriate in base al loro tipo. Quando la funzione onClose() viene eseguita, l'intero flusso audio è stato ricevuto e il servizio non invia ulteriori messaggi binari o di testo.

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

Codici di ritorno WebSocket

Il servizio può inviare i seguenti codici di ritorno al client tramite la connessione WebSocket:

• 1000 indica la normale chiusura della connessione, il che significa che lo scopo per il quale la connessione è stata stabilita è stato soddisfatto.
• 1002 indica che il servizio sta chiudendo la connessione a causa di un errore di protocollo.
• 1006 indica che la connessione è stata chiusa in modo anomalo.
• 1009 indica che la dimensione del frame ha superato il limite di 4 MB.
• 1011 indica che il servizio sta terminando la connessione perché ha riscontrato una condizione imprevista che impedisce di soddisfare la richiesta, ad esempio un argomento non valido. Il codice di ritorno indica anche che il testo di input è troppo lungo.

Se il socket si chiude con un errore, il servizio invia al client un messaggio informativo del tipo {"error": "Specific error message"} prima di chiudersi. Il servizio invia anche messaggi di avvertenza non irreversibile per parametri sconosciuti. Per ulteriori informazioni sui codici di ritorno dell' WebSocket, consultare la Richiesta di commenti(RFC)6455 dell'Internet Engineering Task Force (IETF).

Le implementazioni WebSocket degli SDK possono restituire codici di risposta diversi o aggiuntivi.

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