L'endpoint POST /v1/tts
In questa pagina
Aggiornato il 3 novembre 2026, sulla base della pagina Text to Speech di xAI, del riferimento API Voice e della pagina Pricing. Fonti: Text to Speech · Voice API · Pricing.
Trasforma il testo in audio con l’API Grok
L’API Text-to-Speech di xAI converte qualsiasi testo in audio dal suono naturale con una singola chiamata HTTP. Il punto di ingresso principale è POST /v1/tts, che accetta il tuo testo e restituisce direttamente un file audio binario.
Struttura della richiesta
Invii una richiesta POST a https://api.x.ai/v1/tts con un corpo JSON. Ecco un esempio minimale con curl:
curl -X POST "https://api.x.ai/v1/tts" \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"text": "Hello, and welcome to Corsen Academy.",
"voice_id": "eve",
"language": "en"
}' \
--output audio.mp3
Il server risponde con il file audio binario direttamente nel corpo della risposta. Non c’è alcun involucro JSON: ricevi i byte grezzi del file audio.
Autenticazione
Come per ogni endpoint API di xAI, includi la tua chiave API nell’intestazione Authorization in formato Bearer:
Authorization: Bearer xai-your-api-key
Corpo della richiesta
Il corpo JSON ruota attorno a quattro parametri principali:
text(obbligatorio): il testo da convertire, fino a 60.000 caratteri. Supporta i tag espressivi che scoprirai nelle prossime lezionivoice_id(opzionale): l’ID della voce. Il valore predefinito èeve. I valori non fanno distinzione tra maiuscole e minuscolelanguage(obbligatorio): il codice lingua in formato BCP-47 (en,fr,de, …) oautoper il rilevamento automaticooutput_format(opzionale): un oggetto che configura il codec, la frequenza di campionamento e il bitrate
Altre impostazioni, tutte opzionali, completano la richiesta: speed (velocità di riproduzione, da 0.7 a 1.5, 1.0 di default), replace (una tabella di sostituzioni che corregge la pronuncia di una parola senza modificare il testo inviato), with_timestamps (timestamp per carattere), text_normalization (scrittura estesa di numeri, abbreviazioni e simboli prima della sintesi) e optimize_streaming_latency ("1" per ridurre l’attesa prima del primo chunk audio, a costo di una leggera perdita di qualità nelle giunzioni).
La risposta HTTP
In caso di successo (stato 200), il server restituisce il file audio con il tipo di contenuto corrispondente al formato richiesto:
audio/mpegper MP3 (predefinito)audio/wavper WAVaudio/pcmper PCM grezzoaudio/basicper G.711 μ-law (mulaw)audio/alawper G.711 A-law (alaw)
La risposta non contiene metadati, solo byte audio. L’unica eccezione è with_timestamps: in questo caso la risposta diventa un oggetto JSON che contiene l’audio in base64, la sua durata e il timestamp di ogni carattere. Puoi scrivere la risposta direttamente su un file o trasmetterla in streaming a un lettore audio.
Esempio in Python
import requests
response = requests.post(
"https://api.x.ai/v1/tts",
headers={"Authorization": f"Bearer {api_key}"},
json={
"text": "Here's an example of speech synthesis.",
"voice_id": "rex",
"language": "en"
}
)
with open("output.mp3", "wb") as f:
f.write(response.content)
Esempio in JavaScript (Node.js)
const response = await fetch("https://api.x.ai/v1/tts", {
method: "POST",
headers: {
"Authorization": `Bearer ${process.env.XAI_API_KEY}`,
"Content-Type": "application/json"
},
body: JSON.stringify({
text: "Here's an example of speech synthesis.",
voice_id: "rex",
language: "en"
})
});
const buffer = await response.arrayBuffer();
fs.writeFileSync("output.mp3", Buffer.from(buffer));
Prezzi
Il servizio TTS costa 15 $ per milione di caratteri (prezzi xAI al 3 novembre 2026). Ti viene addebitato il numero di caratteri inviati nel campo text, tag espressivi inclusi; una tabella replace non modifica questo conteggio. Con una media di 1.000 caratteri per richiesta, il costo si aggira intorno a 0,015 $ per chiamata.
Punti chiave
- L’endpoint
POST /v1/ttsè il punto di ingresso principale per la sintesi vocale - La risposta è un file audio binario, non JSON
- Il testo è limitato a 60.000 caratteri per richiesta HTTP; WebSocket non ha limiti totali
- L’autenticazione avviene tramite l’intestazione
Authorization: Bearer - Il costo è di 15 $ per milione di caratteri