Parametri della richiesta TTS
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della pagina Text to Speech di xAI e del riferimento API Voice. Fonti: Text to Speech · Voice API.
Ottimizza la tua sintesi vocale
L’endpoint POST /v1/tts ruota attorno a quattro parametri principali nel corpo della richiesta JSON, più alcune impostazioni opzionali. Ognuno di essi ti offre un controllo preciso sull’audio generato e, comprendendoli, potrai adattare la sintesi al tuo caso d’uso specifico.
Il parametro text
Insieme a language, text è l’unico parametro obbligatorio. Accetta una stringa fino a 60.000 caratteri, che può contenere testo semplice o tag espressivi (trattati nella prossima sezione).
{
"text": "Hello and welcome. Today, we're going to talk about artificial intelligence."
}
Oltre i 60.000 caratteri, la richiesta HTTP viene rifiutata. Per testi più lunghi, xAI raccomanda l’uso di WebSocket, che non ha limiti di lunghezza totale (lezioni da 9 a 12), oppure di suddividere il testo in segmenti di cui concatenare successivamente l’audio. Effettua la divisione su confini naturali (fine frase, fine paragrafo) per ottenere un risultato fluido.
Il parametro voice_id
Questo parametro imposta la voce utilizzata per la sintesi. È opzionale e il valore predefinito è eve. Gli ID non distinguono tra maiuscole e minuscole: Eve, EVE ed eve sono equivalenti.
xAI offre 28 voci integrate (al 3 novembre 2026), le stesse dell’agente vocale, oltre alle voci personalizzate create con le Custom Voices API. Le cinque voci originali, così come descritte da xAI:
- eve: energica e vivace, accento britannico
- ara: calda e amichevole
- rex: sicura e chiara
- sal: fluida ed equilibrata
- leo: autorevole e potente, accento britannico
Le altre 23 (carina, zagan, helix, orion, luna, iris, altair, zenith, perseus, helios, lux, kepler, rigel, cosmo, celeste, ursa, sirius, lumen, castor, naksh, atlas, aurora e liora) sono descritte, con i relativi casi d’uso, nella pagina Text to Speech di xAI; GET /v1/tts/voices restituisce l’elenco aggiornato (lezione 3).
{
"text": "Welcome to this tutorial.",
"voice_id": "rex",
"language": "en"
}
Secondo xAI, ogni voce parla tutte le lingue supportate. La scelta della voce non influisce sul prezzo, che si basa esclusivamente sul numero di caratteri.
Il parametro language
Questo parametro è obbligatorio. Accetta un codice BCP-47 o il valore speciale auto per il rilevamento automatico della lingua.
Le 20 lingue supportate sono:
| Codice | Lingua | Codice | Lingua |
|---|---|---|---|
en | Inglese | ko | Coreano |
fr | Francese | hi | Hindi |
de | Tedesco | bn | Bengalese |
es-ES | Spagnolo (Spagna) | ar-EG | Arabo (Egitto) |
es-MX | Spagnolo (Messico) | ar-SA | Arabo (Arabia Saudita) |
pt-BR | Portoghese (Brasile) | ar-AE | Arabo (EAU) |
pt-PT | Portoghese (Portogallo) | tr | Turco |
it | Italiano | id | Indonesiano |
ru | Russo | vi | Vietnamita |
zh | Cinese | ja | Giapponese |
Il rilevamento automatico (auto) funziona bene per testi in una singola lingua, ma per testi che mescolano più lingue, specifica esplicitamente la lingua principale.
Il parametro output_format
Questo parametro opzionale è un oggetto JSON che controlla il formato di output audio. Contiene tre sotto-parametri.
codec
Il codec imposta il formato di codifica:
mp3(predefinito): formato compresso, ideale per il web e lo streamingwav: formato lossless, qualità superiore ma file più grandipcm: audio grezzo senza header, per pipeline di elaborazionemulaw/ulaw: codec G.711 mu-law per la telefoniaalaw: codec G.711 A-law per la telefonia
sample_rate
La frequenza di campionamento in hertz. Valori accettati: 8000, 16000, 22050, 24000 (predefinito), 44100, 48000.
bit_rate
Il bitrate in bit al secondo, solo per il codec MP3. Valori accettati: 32000, 64000, 96000, 128000 (predefinito), 192000.
{
"text": "High-quality audio for production.",
"voice_id": "ara",
"language": "en",
"output_format": {
"codec": "wav",
"sample_rate": 48000
}
}
Il parametro speed
speed imposta la velocità di riproduzione: 1.0 è la velocità normale (predefinita) e l’intervallo va da 0.7 a 1.5. Un ritmo leggermente più lento aiuta con contenuti educativi densi; sopra 1.2, ascolta sempre nuovamente il risultato.
Combinazioni consigliate
| Caso d’uso | codec | sample_rate | bit_rate |
|---|---|---|---|
| Web / streaming | mp3 | 24000 | 128000 |
| Produzione audio | wav | 48000 | — |
| Telefonia VoIP | mulaw | 8000 | — |
| Pipeline ML | pcm | 16000 | — |
Punti chiave
textelanguagesono gli unici parametri obbligatorivoice_idè opzionale (predefinito:eve) e non distingue tra maiuscole e minuscoleoutput_formatcontrolla codec, frequenza di campionamento e bitrate;speedimposta la velocità (da 0.7 a 1.5)- MP3 a 24 kHz / 128 kbps è un buon equilibrio predefinito tra qualità e dimensione
- Per la telefonia, usa
mulawoalawa 8 kHz