URL di base e prima richiesta
In questa pagina
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.
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 dahttps://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/validationti permette di testare la tua configurazione - Tutti gli endpoint di gestione sono organizzati attorno al
teamId