API Grok: integrare Grok nel proprio codice

Due modi per usare Grok da codice

Gli sviluppatori possono chiamare i modelli Grok principalmente in due modi. Il primo è l'API di xAI, gestita direttamente dall'azienda (ora con il brand SpaceXSI), con chiavi generate su console.x.ai. Il secondo è un model router come OpenRouter, che riunisce i modelli di diversi provider sotto un'unica chiave e un'unica fattura. Entrambi supportano le richieste nel formato Chat Completions di OpenAI, quindi gli SDK ufficiali di OpenAI funzionano subito: basta cambiare l'indirizzo di base e il nome del modello.

Quale opzione scegliere

• API di xAI se vuoi accedere subito a ogni nuova funzione di Grok: l'elenco completo dei modelli, la Responses API, gli strumenti di ricerca web e ricerca su X lato server, la generazione di immagini e video con Grok Imagine, le funzioni vocali, i job in batch e gli sconti sui prompt in cache. Base URL: https://api.x.ai/v1.
• OpenRouter se vuoi passare facilmente da Grok ai modelli di altre aziende senza attivare nuovi contratti, o se hai già un account OpenRouter. Base URL: https://openrouter.ai/api/v1, con gli ID modello preceduti dal prefisso x-ai/. Trovi la procedura di configurazione nella guida introduttiva di OpenRouter.

In ogni caso, conserva la chiave su un server o in una variabile d'ambiente. Non inserirla mai nel codice di una pagina web o di un'app mobile, dove chiunque potrebbe leggerla.

La tua prima richiesta all'API di xAI

Crea una chiave nella console, salvala come XAI_API_KEY e invia un messaggio a Grok 4.7:

curl

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.7",
    "reasoning_effort": "low",
    "messages": [
      {"role": "system", "content": "Sei un assistente conciso."},
      {"role": "user", "content": "Dammi tre consigli per la mia prima maratona."}
    ]
  }'

Python, con la libreria di OpenAI

import os
from openai import OpenAI

grok = OpenAI(
    api_key=os.environ["XAI_API_KEY"],
    base_url="https://api.x.ai/v1",
)

answer = grok.chat.completions.create(
    model="grok-4.3",
    reasoning_effort="medium",
    messages=[{"role": "user", "content": "391 è un numero primo? Mostra i passaggi di verifica."}],
)
print(answer.choices[0].message.content)

Il parametro reasoning_effort controlla per quanto tempo il modello riflette prima di rispondere. Grok 4.3 accetta none, low, medium, high e xhigh (il valore predefinito è low); Grok 4.7 accetta low, medium, high e xhigh (il valore predefinito è high). Per Grok 4.20, xAI mette a disposizione ID distinti: grok-4.20-0309-reasoning e grok-4.20-0309-non-reasoning.

La stessa cosa tramite OpenRouter

Su OpenRouter, imposta la chiave in OPENROUTER_API_KEY e usa gli ID che iniziano con x-ai/. OpenRouter gestisce il ragionamento tramite l'oggetto reasoning. Questo script JavaScript funziona su Node.js 18 o versioni successive:

const endpoint = "https://openrouter.ai/api/v1/chat/completions";

const reply = await fetch(endpoint, {
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    model: "x-ai/grok-4.20",
    reasoning: { enabled: false },
    stream: false,
    messages: [{ role: "user", content: "Riscrivi questo titolo con un tono più calmo: I PREZZI ESPLODONO DI NUOVO" }],
  }),
});
const json = await reply.json();
console.log(json.choices[0].message.content);

Per attivare il ragionamento del modello, invia invece reasoning: { effort: "low" } (oppure medium, high). Aggiungi exclude: true se vuoi che il modello ragioni durante l'elaborazione ma senza mostrare i passaggi nella risposta. Imposta stream: true per ricevere la risposta man mano che viene generata, offrendo un'esperienza molto più fluida nelle interfacce di chat.

Inviare un'immagine

Grok 4.20, 4.3 e 4.7 supportano l'elaborazione delle immagini. Utilizza il formato di messaggio tipico di OpenAI basato su una lista di parti (parts). In base alla documentazione di xAI sono accettate immagini JPEG e PNG fino a 20 MiB; puoi fornire indifferentemente un URL pubblico o un URL in formato data base64.

{
  "model": "grok-4.20-0309-non-reasoning",
  "messages": [{
    "role": "user",
    "content": [
      {"type": "image_url", "image_url": {"url": "https://example.com/receipt.png"}},
      {"type": "text", "text": "Elenca gli articoli e il totale riportati su questo scontrino."}
    ]
  }]
}

ID dei modelli Grok e prezzi

Ecco i modelli di testo attuali indicati da OpenRouter per SpaceXAI, con dimensioni del contesto e tariffe per milione di token (prezzi di listino OpenRouter, ott 2026). L'API di xAI applica le stesse tariffe base per i prompt inferiori a 200.000 token.

Alcuni dettagli dalla pagina modelli e prezzi di xAI (listino prezzi xAI, ott 2026):

• I prompt lunghi costano di più. Quando un prompt raggiunge i 200.000 token, l'intera richiesta viene tariffata al prezzo superiore: $4 / $12 per Grok 4.7, $2.50 / $5 per Grok 4.3 e 4.20.
• L'input memorizzato in cache è più conveniente: $0.50 per milione su Grok 4.7 e $0.20 su Grok 4.3 e 4.20, per prefissi di prompt ripetuti.
• I job in batch che possono attendere beneficiano di uno sconto; OpenRouter elenca inoltre x-ai/grok-4.3:batch a $1 / $2.
• Il contesto varia a seconda della fonte: OpenRouter indica 2.000.000 di token per Grok 4.20, mentre la pagina dei modelli di xAI ne riporta 1.000.000.

I token di ragionamento vengono conteggiati come output, quindi un modello di reasoning può avere un costo per risposta più alto di quanto suggerisca la semplice tariffa per token.

Consigli pratici

• Inizia con Grok 4.20 non-reasoning per chat, riscrittura ed estrazione di dati. È veloce ed economico. Passa a Grok 4.3 o 4.7 quando la precisione su task complessi conta più della velocità.
• Tieni a mente la data di cut-off delle informazioni. Grok 4.7 conosce gli eventi fino a maggio 2026, secondo xAI. Per informazioni più recenti, includi i dati direttamente nel prompt o sfrutta gli strumenti di ricerca web e ricerca su X lato server di xAI, tariffati a chiamata.
• Scrivi un messaggio di sistema dettagliando ruolo, tono e formato di output desiderati, richiedendo un output in JSON con schema se il codice deve analizzare la risposta.
• Gestisci i rate limit. Implementa un meccanismo di retry dopo una breve pausa ogni volta che ricevi una risposta 429.
• Rispetta i termini d'uso. L'uso dell'API è soggetto alle regole di utilizzo accettabile di xAI; puoi usare il campo safety_identifier per etichettare le richieste in base al singolo utente finale.

Risoluzione dei problemi più comuni

• Errore 401 o 403: la chiave non è presente, è stata revocata oppure è configurata nell'ambiente sbagliato. Stampane i primi caratteri nei log del server per verificare che sia caricata correttamente.
• Model not found: controlla il prefisso. OpenRouter richiede x-ai/grok-4.7, mentre xAI richiede semplicemente grok-4.7.
• Risposte vuote o molto lente con un modello di reasoning: spesso significa che ha esaurito i token a disposizione per la fase di ragionamento. Riduci l'effort o aumenta il parametro max_tokens.
• Immagine rifiutata: convertila in JPEG o PNG e assicurati che non superi i limiti di dimensione previsti.

FAQ

L'API di Grok è compatibile con l'SDK di OpenAI?

Sì. Basta puntare l'SDK su https://api.x.ai/v1 con una chiave xAI, oppure su OpenRouter con una chiave OpenRouter, specificando l'ID del modello Grok desiderato.

Esiste un'API gratuita di Grok?

Non è disponibile un piano gratuito permanente. Sia xAI che OpenRouter applicano una tariffazione a consumo per token, anche se i test brevi hanno un costo irrisorio.

Posso generare immagini con l'API di Grok?

Sì, tramite i modelli Grok Imagine di xAI usando l'endpoint dedicato per le immagini. Consulta la nostra guida su Grok Imagine. La nostra interfaccia chat non supporta la generazione di immagini.

Quale modello Grok viene utilizzato su Grok.Online?

La nostra chat offre Grok 4.20 con reasoning disattivato, Grok 4.3 con reasoning effort impostato su low e Grok 4.7 fino a un massimo di 10 messaggi al giorno, il tutto gestito tramite OpenRouter.