Vai al contenuto principale
Italiano— Scegli una lingua
Menu

La connessione WebSocket TTS

Lezione 9 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Sintesi vocale in tempo reale tramite WebSocket
  2. Endpoint WebSocket
  3. Apertura della connessione
  4. Gestione della sessione
  5. HTTP unario versus WebSocket
  6. Quando usare WebSocket
  7. Punti chiave

Aggiornato il 3 novembre 2026, sulla base della pagina Text to Speech di xAI: delta fino a 60.000 caratteri, nessun timeout di connessione e un “permesso di sessione” di 600 secondi. Fonte: Text to Speech.

Sintesi vocale in tempo reale tramite WebSocket

L’API TTS di Grok offre una modalità WebSocket per lo streaming della sintesi vocale. A differenza della modalità HTTP unaria, che attende il completamento dell’elaborazione per restituire l’audio completo, WebSocket invia i chunk audio man mano che vengono generati. È ideale per le applicazioni interattive in cui la latenza percepita deve essere la più bassa possibile.

wss://
Protocollo sicuro
50
Sessioni per team
600 s
Permesso di sessione
∞
Testo illimitato

Endpoint WebSocket

Ti connetti a wss://api.x.ai/v1/tts. I parametri di configurazione vanno inseriti nella query string della connessione iniziale.

Parametri di connessione

ParametroObbligatorioPredefinitoDescrizione
languageSì—Codice BCP-47 o auto
voiceNo—ID di una voce integrata o personalizzata
codecNomp3mp3, wav, pcm, mulaw (o ulaw), alaw
sample_rateNo24000Frequenza di campionamento
bit_rateNo128000Bitrate (solo MP3)

URL di connessione completo

wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3&sample_rate=24000

Apertura della connessione

In JavaScript (browser o Node.js)

const ws = new WebSocket(
  "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3",
  {
    headers: {
      "Authorization": `Bearer ${API_KEY}`
    }
  }
);

ws.onopen = () => {
  console.log("Connessione TTS stabilita");
};

ws.onerror = (error) => {
  console.error("Errore WebSocket:", error);
};

Importante: nel browser, l’API WebSocket nativa non supporta gli header personalizzati. Dovrai passare attraverso il tuo backend per la connessione (vedi la lezione sulla produzione).

In Python con websockets

import asyncio
import websockets
import json

async def connect_tts():
    uri = "wss://api.x.ai/v1/tts?language=en&voice=rex&codec=mp3"
    headers = {"Authorization": f"Bearer {api_key}"}

    async with websockets.connect(uri, additional_headers=headers) as ws:
        print("Connessione TTS stabilita")
        # Invia testo e ricevi audio...

Gestione della sessione

Durata

La pagina Text to Speech di xAI indica due cose che devi leggere insieme: la connessione WebSocket non ha un timeout di richiesta (rimane aperta) e il “permesso di sessione” ha una durata di 600 secondi, senza che la pagina spieghi cosa succede alla scadenza. Per sicurezza, la tua applicazione dovrebbe:

  1. Rilevare quando la connessione si chiude
  2. Riconnettersi automaticamente se necessario
  3. Riprendere l’invio del testo da dove si era interrotto

Sessioni concorrenti

Secondo la pagina Text to Speech, il tuo team è limitato a 50 sessioni WebSocket concorrenti (la pagina Rate limits conteggia le sessioni TTS per livello, a partire da 100). Oltre questo limite, le nuove connessioni vengono rifiutate. Gestisci un pool di connessioni per le applicazioni ad alto traffico.

Più testi su una singola connessione

A differenza della modalità HTTP unaria, dove le richieste scadono dopo 15 minuti, la connessione rimane aperta dopo ogni audio.done: puoi inviare un testo dopo l’altro senza riconnetterti e annullare quello corrente con text.clear (lezione 10).

HTTP unario versus WebSocket

AspettoHTTP unarioWebSocket
LatenzaAudio completo dopo l’elaborazionePrimi byte immediati
Testo max60.000 caratteri per richiestaIllimitato (delta max di 60.000)
Timeout15 minutiNessuno; permesso di sessione di 600 secondi
SessioniN/D50 per team
Casi d’usoBatch, file audioTempo reale, streaming

Quando usare WebSocket

WebSocket è la scelta obbligata non appena entra in gioco il tempo reale. Quando un utente attende una risposta vocale immediata da un chatbot o un assistente vocale, ogni secondo di silenzio prima del primo suono costa in termini di esperienza percepita; WebSocket permette di avviare la riproduzione sui primi frammenti audio, prima ancora che la generazione sia terminata. È anche l’architettura naturale quando il testo stesso arriva gradualmente: l’output in streaming di un LLM si collega direttamente al TTS, delta per delta, senza attendere il testo completo. Inoltre, rimuove il vincolo di lunghezza: non c’è alcun limite globale sul testo totale, solo i singoli delta sono limitati a 60.000 caratteri, sufficienti per vocalizzare un intero documento come flusso continuo.

La modalità HTTP unaria ha ancora il suo posto ovunque il tempo reale non aggiunga valore: generazione di file audio in batch, processi che necessitano del file completo prima di agire (post-elaborazione, archiviazione, invio) e, più semplicemente, qualsiasi architettura che preferisca un round trip stateless alla gestione di una connessione persistente.

Punti chiave

  • TTS WebSocket è disponibile all’indirizzo wss://api.x.ai/v1/tts
  • I parametri vanno nella query string al momento della connessione
  • La connessione non scade da sola, ma la documentazione menziona un permesso di sessione di 600 secondi: pianifica la riconnessione
  • Il limite è di 50 sessioni concorrenti per team
  • Il testo è illimitato (inviato in delta fino a 60.000 caratteri)
  • Usa WebSocket per il tempo reale, HTTP per i batch