Vai al contenuto principale
Italiano— Scegli una lingua
Menu

URL di base e prima richiesta

Lezione 1 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. L’API di gestione: un piano di controllo separato
  2. URL di base
  3. Autenticazione all’API di gestione
  4. Struttura degli endpoint
  5. La tua prima richiesta di gestione
  6. Punti chiave

L’API di gestione: un piano di controllo separato

L’API di gestione di xAI è distinta dall’API di inferenza che utilizzi per inviare prompt a Grok. Ti permette di amministrare le tue risorse: creare e gestire chiavi API, configurare la fatturazione, monitorare l’utilizzo e controllare l’accesso del tuo team. Tutta questa amministrazione avviene tramite un URL dedicato.

URL di base

Questa separazione non è un dettaglio implementativo: riflette una differenza fondamentale tra le due API. Una consuma token ed esegue modelli; l’altra amministra, fattura e concede permessi. Mantenerle su due domini e due set di chiavi distinti garantisce che una chiave applicativa rubata non possa mai creare altre chiavi né leggere le tue informazioni di fatturazione.

https://management-api.x.ai

Non confonderla con https://api.x.ai, che è l’URL per le chiamate di inferenza (completamenti chat, embedding, ecc.). Tutte le richieste di gestione—chiavi, fatturazione, analisi—passano attraverso management-api.x.ai.

2
URL distinti
REST
Architettura standard
JSON
Formato di scambio
Bearer
Autenticazione

Autenticazione all’API di gestione

Il meccanismo di autenticazione è identico—un token Bearer nell’intestazione Authorization—ma la chiave in sé non lo è. Questa è la confusione più comune quando si inizia e produce un errore 401 perfettamente opaco: nulla nel messaggio di errore indica che hai semplicemente presentato la chiave giusta all’API sbagliata.

curl https://management-api.x.ai/auth/management-keys/validation \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

Questa richiesta di validazione (GET /auth/management-keys/validation) ti permette di verificare che la tua chiave di gestione sia valida e attiva. È il punto di ingresso più semplice per testare la tua configurazione.

Chiave di gestione vs Chiave di inferenza

  • Chiave di gestione: concede accesso agli endpoint di management-api.x.ai (amministrazione, fatturazione, analisi)
  • Chiave di inferenza: concede accesso agli endpoint di api.x.ai (chat, embedding, immagini)

Entrambi i tipi di chiave sono generati dalla console xAI, ma i loro ambiti differiscono. Una chiave di inferenza non può accedere agli endpoint di gestione e viceversa.

Struttura degli endpoint

Gli endpoint dell’API di gestione seguono un’organizzazione logica:

  • /auth/teams/{teamId}/api-keys — Gestione delle chiavi API
  • /auth/api-keys/{apiKeyId} — Operazioni su una chiave specifica
  • /auth/teams/{teamId}/models — Modelli accessibili
  • /auth/teams/{teamId}/endpoints — Endpoint ACL disponibili
  • /v1/billing/teams/{teamId}/ — Fatturazione e analisi

Il parametro teamId è l’identificativo del tuo team nella console xAI e struttura quasi tutti gli endpoint. Ogni team ha le proprie chiavi, quote e impostazioni di fatturazione, rendendolo l’unità naturale di isolamento: separare due progetti in due team separa anche i loro budget e accessi, senza alcuna configurazione aggiuntiva.

La tua prima richiesta di gestione

Ecco un esempio completo per validare la tua configurazione:

# Definisci la tua chiave di gestione
export MANAGEMENT_API_KEY="xai-mgmt-..."

# Valida la chiave
curl -s https://management-api.x.ai/auth/management-keys/validation \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

Se la risposta contiene le informazioni sul tuo team e sulla tua chiave, la configurazione funziona. Se ricevi un errore 401, verifica di stare utilizzando una chiave di gestione (non una chiave di inferenza).

Punti chiave

  • L’API di gestione utilizza https://management-api.x.ai, distinto da https://api.x.ai
  • L’autenticazione usa un token Bearer nell’intestazione Authorization
  • Le chiavi di gestione e le chiavi di inferenza hanno ambiti separati
  • L’endpoint GET /auth/management-keys/validation ti permette di testare la tua configurazione
  • Tutti gli endpoint di gestione sono organizzati attorno al teamId