Chiamare l'API con cURL
In questa pagina
Lo strumento universale per testare le API
cURL è uno strumento a riga di comando disponibile su ogni sistema operativo. Ti permette di inviare richieste HTTP senza installare un SDK o scrivere un programma. È lo strumento ideale per testare rapidamente un endpoint, eseguire il debug di una richiesta o automatizzare le chiamate in uno script di shell.
La tua prima richiesta cURL
Ecco come inviare una richiesta all’API Grok con cURL:
curl https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.5",
"messages": [
{"role": "user", "content": "Hello, introduce yourself in one sentence."}
]
}'
Analisi del comando
curl https://api.x.ai/v1/chat/completions: invia una richiesta POST (implicita grazie a-d) all’endpoint-H "Authorization: Bearer $XAI_API_KEY": aggiunge l’intestazione di autenticazione con la tua chiave-H "Content-Type: application/json": specifica che il corpo è in formato JSON-d '{...}': il corpo della richiesta in formato JSON
Utilizzare l’endpoint /v1/responses
Il moderno endpoint /v1/responses offre una sintassi più concisa:
curl https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.5",
"input": "Explain machine learning to me in simple terms."
}'
Nota che input sostituisce messages per le richieste semplici. Puoi passare direttamente una stringa invece di un array di messaggi.
Opzioni utili di cURL
Formattare l’output JSON
La risposta grezza è difficile da leggere. Usa jq per formattarla:
curl -s https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-4.5", "input": "Hello"}' | jq .
L’opzione -s (silent) nasconde la barra di avanzamento di cURL.
Estrarre solo la risposta
Per ottenere il testo della risposta senza i metadati:
curl -s https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "grok-4.5",
"messages": [{"role": "user", "content": "Hello"}]
}' | jq -r '.choices[0].message.content'
Visualizzare le intestazioni di risposta
Per eseguire il debug dei limiti di frequenza o degli errori, aggiungi -i per visualizzare le intestazioni HTTP:
curl -i https://api.x.ai/v1/responses \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "grok-4.5", "input": "Test"}'
Leggere il corpo da un file
Per richieste complesse, salva il JSON in un file:
# request.json
{
"model": "grok-4.5",
"messages": [
{"role": "system", "content": "You are a translator."},
{"role": "user", "content": "Translate into French: Hello world"}
],
"temperature": 0.3
}
Quindi fai riferimento ad esso con @:
curl https://api.x.ai/v1/chat/completions \
-H "Authorization: Bearer $XAI_API_KEY" \
-H "Content-Type: application/json" \
-d @request.json
Eseguire il debug degli errori comuni
- 401 Unauthorized: chiave API non valida o mancante. Controlla con
echo $XAI_API_KEY - 400 Bad Request: JSON malformato. Convalida il tuo JSON con
jq . < request.json - 429 Too Many Requests: hai raggiunto il limite di frequenza. Attendi qualche secondo
- 404 Not Found: controlla l’URL e il percorso dell’endpoint
Punti chiave
- cURL è perfetto per testare ed eseguire il debug senza scrivere codice
- Autenticati con
-H "Authorization: Bearer $XAI_API_KEY" - Usa
jqper formattare e filtrare le risposte JSON - Salva le richieste complesse in file JSON separati