Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Elencare le voci disponibili

Lezione 3 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Scoprire le voci a livello di codice
  2. GET /v1/tts/voices
  3. GET /v1/tts/voices/{voice_id}
  4. Scegliere la voce giusta
  5. Integrare la selezione delle voci nella tua app
  6. Best practices
  7. Punti chiave

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/voices include voice_id, name e language, 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, cosmo o lumen, indicate per l’educazione
  • Assistenza clienti: carina, iris, rigel, celeste, castor, naksh o aurora, indicate per il supporto
  • Pubblicità e demo: altair, zenith, perseus, kepler o lumen, indicate per la pubblicità; eve, energica e vivace, rimane la voce predefinita
  • Narrazione e audiolibri: orion, zagan, altair, perseus o lux
  • Benessere: carina, helios, lux o liora

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/voices non 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/voices elenca tutte le voci disponibili con i relativi metadati
  • GET /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/voices fornisce voice_id, name e language per ciascuna voce
  • Carica le voci dinamicamente invece di codificarle manualmente