Inizia con l'API Text-to-Speech
In questa pagina
Aggiornato il 3 novembre 2026, sulla base delle pagine xAI Text to Speech e Pricing. Fonti: Text to Speech · Pricing.
Testo in ingresso, audio in uscita
L’API Text-to-Speech di Grok fa una cosa sola, e la fa bene: trasforma il testo in audio di alta qualità. Mentre il Voice Agent gestisce un dialogo con turni di parola e interruzioni, il TTS funziona rigorosamente in un solo senso: invii del testo e ricevi dell’audio. Questa semplicità ne fa lo strumento ideale ogni volta che nessuno deve rispondere alla macchina: articoli narrati, messaggi di segreteria telefonica, voice-over per moduli di e-learning, notifiche audio.
HTTP o WebSocket: due modi per chiamare il servizio
La modalità HTTP è la più diretta. Invii una richiesta POST con il tuo testo e la risposta contiene il file audio completo, in MP3 per impostazione predefinita:
curl -X POST "https://api.x.ai/v1/tts" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-o output.mp3 \
-d '{
"text": "Hello and welcome to Corsen Academy.",
"voice_id": "ara",
"language": "en"
}'
Nota l’opzione -o output.mp3: il corpo della risposta è audio grezzo, non un JSON che racchiude un link. Questa modalità è perfetta per la generazione in background, come un batch notturno che produce versioni audio dei tuoi articoli, dato che nessuno aspetta davanti a uno schermo.
La modalità WebSocket risponde a un’esigenza diversa: ascoltare l’audio prima che l’intero testo sia stato sintetizzato. Apri una connessione e passi i parametri nell’URL:
wss://api.x.ai/v1/tts?language=en&voice=ara&codec=mp3
Invii quindi il testo a pezzi con text.delta, segnali la fine con text.done e l’audio torna come chunk in base64 su audio.delta. Lo streaming elimina il limite di lunghezza della modalità HTTP e, soprattutto, ti permette di sintetizzare man mano che procedi, cosa essenziale quando il testo stesso viene ancora generato da un modello.
Parametri della richiesta HTTP
| Parametro | Tipo | Obbligatorio | Descrizione |
|---|---|---|---|
text | string | Sì | Il testo da convertire, fino a 60.000 caratteri |
voice_id | string | No | La voce da utilizzare (predefinito: eve) |
language | string | Sì | Codice BCP-47 (en, fr, de, …) o auto |
output_format | object | No | Codec, frequenza di campionamento e bit rate |
speed | number | No | Velocità di riproduzione, da 0,7 a 1,5 (predefinito: 1,0) |
Due punti meritano attenzione. language è obbligatorio, il che spesso sorprende: il servizio non indovina la lingua del tuo testo a meno che tu non glielo chieda esplicitamente con il valore auto. Inoltre, voice_id utilizza esattamente le stesse voci del Voice Agent (28 voci integrate al 3 novembre 2026, tra cui eve, ara, rex, sal e leo, più le tue voci personalizzate) e non distingue tra maiuscole e minuscole. La stessa persona vocale può quindi alimentare sia il tuo agente conversazionale che i tuoi contenuti registrati, un vantaggio da sfruttare per la coerenza del brand.
Scegliere il formato di output
Il campo output_format controlla il codec e la qualità:
{
"text": "Text to convert.",
"voice_id": "rex",
"language": "en",
"output_format": {
"codec": "wav",
"sample_rate": 44100
}
}
Scegli il codec in base a ciò che accadrà al file successivamente. mp3 è adatto all’uso generale: ben compresso e riproducibile ovunque, è l’impostazione predefinita sensata per un sito web o un podcast. wav è senza perdita, quindi più pesante, ma è ciò che ti serve quando un editor deve rielaborare la traccia. pcm fornisce audio grezzo, per pipeline di elaborazione che non hanno bisogno di un contenitore. Infine, mulaw e alaw sono i codec telefonici G.711, per sistemi di telecomunicazione che li richiedono.
Le frequenze di campionamento vanno da 8000 a 48000 Hz, con un predefinito di 24000 Hz, che copre la stragrande maggioranza degli usi. Per MP3, il bit rate va da 32000 a 192000 bps, con un predefinito di 128000. Salire a 192000 per la voce parlata non aggiunge quasi nulla all’esperienza di ascolto e rende i tuoi file un terzo più grandi: riserva quella banda per contenuti che mescolano musica e voce.
Interrogare il catalogo delle voci
L’API espone due endpoint di sola lettura che completano la generazione. GET /v1/tts/voices restituisce tutte le voci disponibili con i relativi metadati, mentre GET /v1/tts/voices/{voice_id} restituisce gli stessi campi (voice_id, name, language) per una singola voce; il tono e i casi d’uso di ciascuna voce sono descritti nella pagina xAI Text to Speech. Invece di codificare rigidamente i nomi delle voci nella tua interfaccia, popula il selettore voci da questi endpoint: così la tua app rimarrà corretta anche il giorno in cui il catalogo cambierà.
Punti chiave
- Il TTS converte il testo in audio tramite HTTP (semplice) o WebSocket (streaming)
- Costa $15 per milione di caratteri, con un massimo di 60.000 caratteri per richiesta HTTP
- 28 voci integrate, cinque codec e sei frequenze di campionamento offrono grande flessibilità
- La modalità WebSocket non ha limiti sulla lunghezza totale del testo (ogni delta è limitato a 60.000 caratteri)
- È richiesto un codice BCP-47 per specificare la lingua (o
autoper il rilevamento automatico)