Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'endpoint POST /v1/tts

Lezione 1 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. Trasforma il testo in audio con l’API Grok
  2. Struttura della richiesta
  3. La risposta HTTP
  4. Prezzi
  5. Punti chiave

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.

60,000
Caratteri massimi per richiesta
28
Voci integrate
20
Lingue supportate
$15
Per milione di caratteri

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 lezioni
  • voice_id (opzionale): l’ID della voce. Il valore predefinito è eve. I valori non fanno distinzione tra maiuscole e minuscole
  • language (obbligatorio): il codice lingua in formato BCP-47 (en, fr, de, …) o auto per il rilevamento automatico
  • output_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/mpeg per MP3 (predefinito)
  • audio/wav per WAV
  • audio/pcm per PCM grezzo
  • audio/basic per G.711 μ-law (mulaw)
  • audio/alaw per 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