Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Chiamare l'API con cURL

Lezione 8 di 14 Aggiornata il 30 luglio 2026 Sviluppatore
In questa pagina
  1. Lo strumento universale per testare le API
  2. La tua prima richiesta cURL
  3. Utilizzare l’endpoint /v1/responses
  4. Opzioni utili di cURL
  5. Leggere il corpo da un file
  6. Eseguire il debug degli errori comuni
  7. Punti chiave

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 jq per formattare e filtrare le risposte JSON
  • Salva le richieste complesse in file JSON separati