API di gestione: gestione di chiavi e fatturazione
In questa pagina
Gestisci il tuo account senza la console
L’API di gestione xAI è un’interfaccia REST dedicata alla gestione del tuo account Enterprise. Mentre l’API di inferenza (api.x.ai) interroga i modelli, l’API di gestione (management-api.x.ai) amministra le tue risorse. La distinzione potrebbe sembrare minima. Non lo è. Tutto ciò che altrimenti richiederebbe a qualcuno di aprire la console web e fare clic diventa qui automatizzabile: tracciabile, riproducibile e integrabile con gli strumenti che i tuoi team utilizzano già.
Provisioning e rotazione delle chiavi
La creazione di chiavi tramite API ti consente di automatizzare il provisioning per una nuova applicazione o ambiente:
curl -X POST "https://management-api.x.ai/auth/teams/{teamId}/api-keys" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "cle-production-chatbot",
"acls": ["api-key:endpoint:chat", "api-key:model:grok-4.3"],
"qps": 10,
"qpm": 100,
"tpm": 1000000,
"expireTime": "2026-12-31T23:59:59Z"
}'
I parametri di questa richiesta definiscono completamente l’ambito della chiave:
- name: identificatore leggibile dall’uomo per la chiave
- acls: elenco delle autorizzazioni (endpoint e modelli autorizzati)
- qps/qpm/tpm: limiti di frequenza al secondo, al minuto e token al minuto
- expireTime: data di scadenza automatica
Impostare expireTime al momento della creazione è l’abitudine che ti risparmia più problemi a lungo termine: una chiave emessa per un pilota di tre mesi scade da sola invece di sopravvivere indefinitamente in un file di configurazione che nessuno legge più.
La rotazione regolare delle chiavi segue la stessa igiene di sicurezza. L’endpoint dedicato genera una nuova chiave segreta e invalida quella vecchia:
curl -X POST "https://management-api.x.ai/auth/api-keys/{apiKeyId}/rotate" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Attenzione: la vecchia chiave segreta viene invalidata immediatamente e permanentemente. Preparati a distribuire il nuovo valore nel tuo gestore di segreti prima di eseguire il comando, mai dopo. Tre endpoint di sola lettura completano il set: GET /auth/teams/{teamId}/api-keys elenca tutte le chiavi del team, GET /auth/api-keys/{apiKeyId}/propagation verifica che la chiave sia propagata su tutti i nodi e GET /auth/teams/{teamId}/models elenca i modelli accessibili con i relativi prezzi. Il secondo è quello che consulti subito dopo una rotazione, quando un’applicazione restituisce ancora errori di autenticazione e non sei sicuro se si tratti di un bug dell’applicazione o semplicemente di un ritardo di propagazione.
Traccia e controlla la fatturazione
Il recupero delle informazioni di fatturazione utilizza un endpoint dedicato:
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/billing-info" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Recuperi la cronologia delle fatture con il filtro per periodo, qui per marzo 2026:
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/invoices?billingCycle.year=2026&billingCycle.month=3" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Ogni fattura ha uno stato tra PENDING, PAID, FAILED e WILL_NEVER_BE_CHARGED. Rilevare uno stato FAILED nel tuo monitoraggio è di gran lunga meglio che scoprire l’incidente tramite un’interruzione del servizio un lunedì mattina.
Per prevenire sforamenti di budget, configura un limite mensile:
curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{"monthlyLimit": 5000}'
Se operi in modalità prepagata, controlla il saldo allo stesso modo:
# Check balance
curl "https://management-api.x.ai/v1/billing/teams/{teamId}/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_KEY"
Ricorda che i crediti prepagati sono non rimborsabili, salvo obbligo di legge. Dimensiona i tuoi acquisti in base al consumo osservato nell’arco di diverse settimane, non su proiezioni di crescita ottimistiche.
Monitora il tuo consumo alla giusta granularità
L’endpoint di analisi ti consente di tracciare l’utilizzo con una granularità fine:
curl -X POST "https://management-api.x.ai/v1/billing/teams/{teamId}/usage" \
-H "Authorization: Bearer $MANAGEMENT_KEY" \
-H "Content-Type: application/json" \
-d '{
"analyticsRequest": {
"timeRange": {
"startTime": "2026-03-01 00:00:00",
"endTime": "2026-04-01 00:00:00",
"timezone": "UTC"
},
"timeUnit": "DAY",
"values": [{"name": "tokens", "aggregation": "SUM"}],
"groupBy": ["model"]
}
}'
Questa richiesta restituisce il consumo giornaliero di token, suddiviso per modello, per il mese di marzo. Cambiando timeUnit, passi da una visione mensile a una per minuto: i valori possibili sono MONTH, CALENDAR_WEEK, DAY, HOUR, QUARTER_HOUR e MINUTE. Le aggregazioni vanno ben oltre i semplici totali, con SUM, AVG, MIN, MAX, P50, P90, P99 e COUNT. I percentili caratterizzano efficacemente il carico perché le medie appianano proprio quei picchi che determinano la capacità di cui hai effettivamente bisogno.
L’API di gestione trova quindi il suo posto nella tua catena di strumenti. Provisioni le chiavi da Terraform o Pulumi proprio come un database, la tua pipeline CI/CD crea chiavi effimere per gli ambienti di test e le elimina al termine dell’esecuzione, gli script di monitoraggio lanciano allarmi prima che venga raggiunto il limite di spesa e le tue dashboard interne visualizzano il consumo senza che un umano debba esportare un CSV ogni lunedì.
Punti chiave
- L’API di gestione su management-api.x.ai gestisce chiavi, fatturazione e metriche
- La rotazione delle chiavi invalida permanentemente la vecchia chiave segreta
- I limiti di spesa proteggono dagli sforamenti di budget
- Le analisi di utilizzo offrono una granularità dal minuto al mese
- Integra l’API di gestione nei tuoi strumenti infrastrutturali per automatizzare l’amministrazione