Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Una semplice richiesta POST /v1/responses

Lezione 9 di 14 Aggiornata il 3 novembre 2026 Sviluppatore
In questa pagina
  1. La tua prima chiamata riuscita
  2. Struttura della richiesta
  3. Anatomia della risposta
  4. Parametri opzionali comuni
  5. Continuare una conversazione
  6. Tracciare i costi
  7. Punti chiave

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_p a 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 utilizzare
  • input: 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 seguito
  • status: completed quando la generazione è terminata
  • output: un array contenente i messaggi generati
  • usage: 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.7 e top_p=0.95 e 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: model e input
  • La risposta si trova in output[0].content[0].text
  • Usa previous_response_id per conversazioni multi-turno
  • Il campo usage ti aiuta a tracciare il consumo di token