Una semplice richiesta POST /v1/responses
In questa pagina
Aggiornato il 3 novembre 2026, sulla base delle best practice e del riferimento API di xAI: la temperatura è limitata a 1 e xAI raccomanda 0,7 con
top_pa 0,95. Fonte: Best practices.
La tua prima chiamata riuscita
Hai il tuo account, la tua chiave API e un SDK installato. È il momento di inviare la tua prima richiesta alle API di Grok e comprendere la struttura della risposta. Questa lezione si concentra sull’endpoint principale, /v1/responses, il più moderno e raccomandato.
Struttura della richiesta
L’endpoint POST /v1/responses richiede almeno due parametri:
model: l’ID del modello da utilizzareinput: il testo della tua richiesta (o un array di contenuti per casi avanzati)
Richiesta minima in Python
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="What's the most widely used programming language in 2026?"
)
print(response.output[0].content[0].text)
Con istruzioni di sistema
Il parametro instructions ti permette di definire il comportamento del modello:
response = client.responses.create(
model="grok-4.5",
instructions="You are a web development expert. Answer concisely.",
input="What's the difference between SSR and SSG?"
)
Anatomia della risposta
L’API restituisce un oggetto JSON strutturato. Ecco i campi principali:
{
"id": "resp-abc123",
"object": "response",
"status": "completed",
"model": "grok-4.5",
"output": [
{
"type": "message",
"content": [
{
"type": "output_text",
"text": "The model's answer appears here."
}
],
"status": "completed"
}
],
"usage": {
"input_tokens": 42,
"output_tokens": 156,
"total_tokens": 198
}
}
Campi importanti
id: l’ID univoco della risposta, utile per recuperarla in seguitostatus:completedquando la generazione è terminataoutput: un array contenente i messaggi generatiusage: contatori di token per tracciare il tuo consumo
Parametri opzionali comuni
Controllare la creatività
response = client.responses.create(
model="grok-4.5",
input="Suggest a name for an AI startup.",
temperature=0.7, # il valore raccomandato da xAI
top_p=0.95,
)
- L’API accetta una temperatura da 0 a 2, ma limita qualsiasi valore superiore a 1
- xAI raccomanda
temperature=0.7etop_p=0.95e sconsiglia di discostarsene: la qualità solitamente diminuisce - Per maggiore creatività, chiedilo esplicitamente nel prompt («suggerisci nomi inaspettati»)
Limitare la lunghezza
response = client.responses.create(
model="grok-4.5",
input="Summarize the concept of machine learning.",
max_output_tokens=200 # Limita la risposta
)
Attivare il ragionamento
Per i modelli di ragionamento, regola lo sforzo cognitivo:
response = client.responses.create(
model="grok-4.20-0309-reasoning",
input="Solve this problem: if 3x + 7 = 22, what is x?",
reasoning={"effort": "high"}
)
I livelli possibili sono low, medium e high.
Continuare una conversazione
L’endpoint /v1/responses supporta conversazioni multi-turno tramite il parametro previous_response_id:
# Primo messaggio
r1 = client.responses.create(
model="grok-4.5",
input="I'm building an API in Python."
)
# Secondo messaggio (il modello ricorda il contesto)
r2 = client.responses.create(
model="grok-4.5",
input="Which framework do you recommend?",
previous_response_id=r1.id
)
Questo approccio è più semplice rispetto alla gestione manuale dello storico dei messaggi.
Tracciare i costi
Il campo usage nella risposta ti permette di calcolare il costo di ogni chiamata. Il campo output_tokens_details.reasoning_tokens mostra quanti token sono stati utilizzati per il ragionamento interno del modello (questi token sono fatturati ma non appaiono nella risposta).
Punti chiave
- L’endpoint
POST /v1/responsesè il più moderno e raccomandato - Due parametri obbligatori:
modeleinput - La risposta si trova in
output[0].content[0].text - Usa
previous_response_idper conversazioni multi-turno - Il campo
usageti aiuta a tracciare il consumo di token