Elencare le voci disponibili
In questa pagina
Aggiornato il 3 novembre 2026, sulla base del riferimento API Voice di xAI e della pagina Text to Speech: la risposta di
GET /v1/tts/voicesincludevoice_id,nameelanguage, e xAI offre 28 voci integrate. Fonti: Voice API · Text to Speech.
Scoprire le voci a livello di codice
Invece di codificare manualmente l’elenco delle voci nella tua applicazione, l’API xAI mette a disposizione un endpoint dedicato per recuperare dinamicamente le voci disponibili. In questo modo, rimani aggiornato ogni volta che vengono aggiunte nuove voci.
GET /v1/tts/voices
Questo endpoint restituisce l’elenco di tutte le voci disponibili per il TTS. Non richiede parametri nel corpo della richiesta.
curl -X GET "https://api.x.ai/v1/tts/voices" \
-H "Authorization: Bearer $XAI_API_KEY"
La risposta è un oggetto JSON contenente un array voices. Secondo il riferimento API, ogni voce ha tre campi: voice_id, l’ID in minuscolo da passare nelle tue richieste; name, un nome visualizzabile; e language, un codice lingua che può essere null.
Struttura della risposta
{
"voices": [
{"voice_id": "eve", "name": "…", "language": "…"},
{"voice_id": "ara", "name": "…", "language": "…"}
]
}
I puntini di sospensione rappresentano valori che il riferimento non fornisce come esempi: stampa la risposta reale una volta prima di farci affidamento. Il tono e i casi d’uso di ciascuna voce non sono presenti in questa risposta; sono descritti nella pagina Text to Speech di xAI.
GET /v1/tts/voices/{voice_id}
Per ottenere i dettagli di una voce specifica, aggiungi il suo ID al percorso:
curl -X GET "https://api.x.ai/v1/tts/voices/rex" \
-H "Authorization: Bearer $XAI_API_KEY"
Questa chiamata restituisce gli stessi campi (voice_id, name, language) solo per la voce richiesta.
Scegliere la voce giusta
xAI offre 28 voci integrate (al 3 novembre 2026) e, per la maggior parte di esse, descrive gli utilizzi più indicati. Ecco alcuni suggerimenti tratti da quella pagina:
- Contenuti educativi:
luna,cosmoolumen, indicate per l’educazione - Assistenza clienti:
carina,iris,rigel,celeste,castor,nakshoaurora, indicate per il supporto - Pubblicità e demo:
altair,zenith,perseus,keplerolumen, indicate per la pubblicità;eve, energica e vivace, rimane la voce predefinita - Narrazione e audiolibri:
orion,zagan,altair,perseusolux - Benessere:
carina,helios,luxoliora
Le cinque voci originali (eve, ara, rex, sal, leo) non hanno casi d’uso elencati: xAI le descrive semplicemente come energiche e vivaci (accento britannico), calde e amichevoli, sicure e chiare, fluide ed equilibrate, autorevoli e potenti (accento britannico).
Integrare la selezione delle voci nella tua app
Ecco un esempio che carica dinamicamente le voci disponibili:
import requests
def get_available_voices(api_key):
response = requests.get(
"https://api.x.ai/v1/tts/voices",
headers={"Authorization": f"Bearer {api_key}"}
)
response.raise_for_status()
return response.json()["voices"]
def synthesize(api_key, text, voice_id="eve", language="en"):
voices = get_available_voices(api_key)
valid_ids = [v["voice_id"] for v in voices]
if voice_id.lower() not in valid_ids:
raise ValueError(f"Unknown voice '{voice_id}'. Available: {valid_ids}")
response = requests.post(
"https://api.x.ai/v1/tts",
headers={"Authorization": f"Bearer {api_key}"},
json={"text": text, "voice_id": voice_id, "language": language}
)
return response.content
Questo approccio ti protegge dagli errori di battitura negli ID delle voci e ti permette di offrire ai tuoi utenti un elenco sempre aggiornato.
Best practices
- Metti in cache l’elenco delle voci: l’endpoint
/v1/tts/voicesnon cambia spesso, quindi una singola chiamata all’avvio dell’app è sufficiente - Offri un’anteprima: permetti agli utenti di ascoltare un campione di ciascuna voce prima di sceglierla
- Salva la preferenza: una volta che un utente ha scelto una voce, memorizza la scelta per le sessioni future
- Testa nella lingua di destinazione: una voce che suona bene in inglese potrebbe suonare diversamente in un’altra lingua. Testa sempre nella lingua della tua app
Punti chiave
GET /v1/tts/voiceselenca tutte le voci disponibili con i relativi metadatiGET /v1/tts/voices/{voice_id}fornisce i dettagli di una voce specifica- Sono disponibili 28 voci integrate; il loro tono e i casi d’uso sono descritti nella pagina Text to Speech di xAI
- La risposta di
GET /v1/tts/voicesforniscevoice_id,nameelanguageper ciascuna voce - Carica le voci dinamicamente invece di codificarle manualmente