Vai al contenuto principale
Italiano— Scegli una lingua
Menu

L'API xAI per gli sviluppatori

Lezione 15 di 16 Aggiornata il 29 luglio 2026 Principiante
In questa pagina
  1. Integra Grok nelle tue applicazioni
  2. Prerequisiti
  3. Configurazione iniziale
  4. La tua prima richiesta
  5. Cosa espone l’API
  6. Scegli il tuo modello
  7. Limiti di velocità e best practice
  8. Punti chiave

Integra Grok nelle tue applicazioni

Tutto ciò che hai imparato a fare nell’interfaccia di Grok può essere attivato dal tuo codice. L’API xAI porta queste funzionalità nelle tue app, nei tuoi siti web e nei tuoi servizi: la conversazione smette di essere un luogo in cui andare e diventa una funzione che il tuo prodotto chiama.

Prerequisiti

Hai bisogno di quattro cose prima di scrivere la tua prima riga di codice:

  1. Un account xAI creato su accounts.x.ai
  2. Una chiave API generata su console.x.ai
  3. Un metodo di pagamento configurato (per andare oltre la quota gratuita)
  4. Un ambiente di sviluppo Python o JavaScript

Le prime due sono cose che hai già fatto in questo corso: l’account gestisce l’autenticazione e la chiave identifica la tua applicazione presso l’API. Il metodo di pagamento entra in gioco solo quando il tuo utilizzo supera la quota gratuita, cosa che accade più velocemente di quanto pensi non appena un servizio viene eseguito continuamente. Per quanto riguarda l’ambiente, Python e JavaScript offrono gli strumenti migliori, ma poiché l’API parla HTTP, qualsiasi linguaggio in grado di inviare una richiesta va bene.

Configurazione iniziale

Il primo passo consiste nell’archiviare la tua chiave API in modo sicuro, in una variabile d’ambiente:

export XAI_API_KEY="xai-your-key-here"

Non inserire mai la tua chiave direttamente nel codice sorgente. Il motivo è banale: una chiave scritta in un file finisce prima o poi in un repository Git, e una chiave inviata a un repository pubblico viene sfruttata nel giro di pochi minuti da bot che scansionano i commit, mentre la fattura rimane a tuo nome.

Il passo successivo è scegliere un SDK. L’SDK nativo xAI per Python si installa con pip install xai-sdk. Se il tuo codice chiama già OpenAI, la libreria openai funziona così com’è, grazie alla compatibilità del formato. Sul lato JavaScript, aggiungi l’SDK AI di Vercel con npm install ai @ai-sdk/xai, che si integra con le app React e Next.js.

La tua prima richiesta

Con l’SDK nativo, la creazione del client e l’apertura di una conversazione richiedono tre righe:

from xai_sdk import Client
import os

client = Client(api_key=os.getenv("XAI_API_KEY"))
response = client.chat.create(model="grok-4.5")

Il percorso compatibile con OpenAI è altrettanto diretto: cambia solo il base_url rispetto al codice esistente, motivo per cui molti team effettuano il passaggio in pochi minuti.

from openai import OpenAI
import os

client = OpenAI(
    api_key=os.getenv("XAI_API_KEY"),
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.5",
    input="Explain machine learning to me in 3 sentences."
)

Per verificare che una chiave funzioni prima ancora di scrivere codice, nulla batte una chiamata da riga di comando:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.5",
    "input": "Hi, how are you?"
  }'

Cosa espone l’API

La base è la generazione di testo (risposte conversazionali, scrittura, analisi), insieme a una modalità di ragionamento che risolve problemi complessi passo dopo passo. Lo streaming si aggiunge a ciò fornendo la risposta token per token invece di attendere il termine della generazione.

Un secondo set dà accesso alle informazioni: ricerca in tempo reale sul web e su X, e RAG, che interroga collezioni di documenti che hai costruito. L’aspetto multimodale copre la comprensione delle immagini che fornisci, la generazione di immagini e video con grok-imagine e la voce, con conversazioni parlate e TTS.

Infine, tre meccanismi rendono l’API programmabile in senso stretto: il function calling, che consente al modello di chiamare le tue funzioni; gli output strutturati, che garantiscono JSON utilizzabili senza post-elaborazioni fragili; e l’esecuzione del codice lato server.

Scegli il tuo modello

Il ragionamento varia a seconda del modello. grok-4.7, il fiore all’occhiello, offre un ragionamento configurabile: il parametro reasoning_effort (low, medium, high o xhigh) imposta la profondità del pensiero, richiesta per richiesta. grok-4.3 rimane l’opzione economica con contesto molto lungo, a circa metà prezzo. Esistono versioni dei modelli senza ragionamento per compiti semplici: la riformulazione o la classificazione non richiedono una deliberazione interna.

Le convenzioni di denominazione influenzano la stabilità della tua applicazione:

  • grok-4.20: l’ultima versione stabile consigliata
  • grok-4.20-latest: la versione più recente (può cambiare)
  • grok-4.20-0309: una versione bloccata a una data specifica (9 marzo)

In produzione, una versione bloccata protegge i tuoi prompt da modifiche silenziose del modello; latest va bene per l’esplorazione, purché tu accetti che il comportamento possa cambiare.

Limiti di velocità e best practice

L’API applica limiti di velocità per mantenere stabile il servizio: sul livello di ingresso, circa 10 milioni di token al minuto e 1.800 richieste al minuto per modelli come grok-4.3, e di più man mano che il tuo livello sale. I modelli di generazione di immagini e video hanno i propri limiti, molto più bassi, da 30 a 300 richieste al minuto a seconda del modello, quindi tienili d’occhio per un servizio rivolto ai consumatori.

Alcune abitudini distinguono un prototipo da un’integrazione solida. Attiva lo streaming per le risposte lunghe, perché trenta secondi davanti a uno schermo bianco sembrano un’interruzione del servizio. Passa un ID conversazione per beneficiare della cache. Instrada ogni compito al modello giusto: grok-4.3 per volumi semplici, grok-4.20 per il ragionamento. Gestisci gli errori con nuovi tentativi e backoff esponenziale, altrimenti un picco di traffico si trasforma in una valanga di richieste rifiutate. E monitora il tuo utilizzo nella console prima di scoprire il totale alla fine del mese.

Punti chiave

  • L’API xAI è compatibile con il formato OpenAI, il che rende facile la migrazione
  • Sono disponibili diversi SDK: xAI nativo, OpenAI e l’SDK AI di Vercel
  • L’API copre testo, immagini, video, voce e ricerca
  • Due livelli di modelli: grok-4.7 (fiore all’occhiello, ragionamento configurabile) e grok-4.3 (economico, contesto 1M)
  • Archivia sempre la tua chiave API in una variabile d’ambiente, mai hardcoded