Creare una risposta con POST /v1/responses
In questa pagina
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 utilizzareinput: 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:
- Utilizzi il modello
grok-4.20-0309-reasoning - Definisci le istruzioni di sistema per un assistente tecnico
- 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: richiedemodeleinputinputaccetta testo semplice o un array strutturato con ruoliinstructionsdefinisce il comportamento di sistema del modello- L’autenticazione avviene tramite l’intestazione
Authorization: Bearer - L’SDK OpenAI è compatibile con xAI modificando il
base_url