Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Creare una risposta con POST /v1/responses

Lezione 2 di 16 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. La tua prima richiesta
  2. Autenticazione
  3. Richiesta minima
  4. Con l’SDK Python
  5. Input semplice vs strutturato
  6. Il parametro instructions
  7. Esercizio pratico
  8. Punti chiave

La tua prima richiesta

L’endpoint POST /v1/responses è il punto di ingresso principale per le API Responses. È qui che invii i tuoi prompt e ricevi le risposte dai modelli Grok. In questa lezione, imparerai a costruire e inviare la tua prima richiesta.

Autenticazione

Tutte le richieste richiedono un’intestazione di autenticazione con la tua chiave API xAI:

Authorization: Bearer $XAI_API_KEY

Puoi generare le tue chiavi su console.x.ai. Tienile segrete: non inserirle mai in un repository Git.

Richiesta minima

Ecco la richiesta più semplice possibile:

curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "input": "Explain what machine learning is in 3 sentences."
  }'

Due campi sono sufficienti:

  • model: l’ID del modello Grok da utilizzare
  • input: il tuo prompt, come testo semplice

Con l’SDK Python

Se utilizzi l’SDK OpenAI (compatibile con xAI), la sintassi è simile:

from openai import OpenAI

client = OpenAI(
    api_key="xai-...",
    base_url="https://api.x.ai/v1"
)

response = client.responses.create(
    model="grok-4.20-0309-reasoning",
    input="Explain what machine learning is in 3 sentences."
)

print(response.output[0].content[0].text)

Input semplice vs strutturato

Il parametro input accetta due formati.

Testo semplice

{
  "model": "grok-4.20-0309-reasoning",
  "input": "What is the capital of France?"
}

Array strutturato

Per input multimodali o ruoli espliciti:

{
  "model": "grok-4.20-0309-reasoning",
  "input": [
    {
      "role": "user",
      "content": "Analyze this image and describe what you see."
    }
  ]
}

Il formato ad array ti offre maggiore controllo, specialmente per includere immagini o specificare ruoli diversi.

Il parametro instructions

Per definire il comportamento di sistema del modello, usa instructions invece di aggiungere un messaggio di sistema in input:

{
  "model": "grok-4.20-0309-reasoning",
  "instructions": "You are a French cuisine expert. Always respond including a chef's tip.",
  "input": "How do I make a successful béchamel?"
}

Il campo instructions equivale al system prompt nelle Chat Completions. Definisce il comportamento globale del modello per l’intera conversazione.

Esercizio pratico

Prova a costruire una richiesta che:

  1. Utilizzi il modello grok-4.20-0309-reasoning
  2. Definisci le istruzioni di sistema per un assistente tecnico
  3. Ponga una domanda su Python
curl https://api.x.ai/v1/responses \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20-0309-reasoning",
    "instructions": "You are a senior Python developer. Give concise code examples.",
    "input": "How do I read a JSON file in Python?"
  }'

Punti chiave

  • POST /v1/responses è l’endpoint principale: richiede model e input
  • input accetta testo semplice o un array strutturato con ruoli
  • instructions definisce il comportamento di sistema del modello
  • L’autenticazione avviene tramite l’intestazione Authorization: Bearer
  • L’SDK OpenAI è compatibile con xAI modificando il base_url