Saldo e ricariche automatiche
In questa pagina
Monitorare e automatizzare le ricariche
Combinare il monitoraggio del saldo prepagato con le analisi di utilizzo ti permette di configurare un sistema di ricarica intelligente. Invece di effettuare ricariche manuali, puoi automatizzare il processo basandoti su soglie e previsioni di consumo.
Verificare i dettagli del saldo
L’endpoint restituisce due elementi che non devi confondere: il saldo istantaneo e lo storico delle transazioni. Il primo risponde alla domanda «Posso ancora chiamare l’API?», il secondo a «Quanto velocemente sto consumando?». È il secondo che ti consente di anticipare gli eventi e, di conseguenza, l’unico su cui puoi basare l’automazione.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
La risposta contiene il saldo corrente e lo storico delle transazioni (acquisti e consumi).
Sistema di ricarica automatica
Un sistema di ricarica automatica ben configurato si basa su due numeri, uno dei quali viene spesso dimenticato. La soglia di attivazione deve coprire il tuo consumo durante il tempo di reazione: se controlli una volta al giorno, ti serve almeno un giorno di credito in anticipo, altrimenti l’automazione scatterà dopo il superamento del limite. Il tetto mensile è la salvaguardia che manca più spesso: senza di esso, un loop difettoso nella tua applicazione può attivare ricarica dopo ricarica, e i crediti xAI non sono rimborsabili.
Questi due valori non vengono impostati arbitrariamente: la prossima sezione mostra come calcolarli in base al tuo consumo effettivo.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Configurazione
MIN_BALANCE = 50.00 # Soglia di ricarica
TOP_UP_AMOUNT = 200.00 # Importo della ricarica
MAX_MONTHLY = 1000.00 # Tetto mensile
def get_balance():
"""Ottieni il saldo prepagato corrente."""
resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
return resp.json().get("balance", 0)
def get_monthly_top_ups():
"""Calcola il totale delle ricariche per il mese corrente."""
resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
# Filtra le transazioni per il mese corrente
transactions = resp.json().get("transactions", [])
current_month = datetime.now().strftime("%Y-%m")
monthly_total = sum(
t.get("amount", 0)
for t in transactions
if t.get("type") == "top-up" and t.get("date", "").startswith(current_month)
)
return monthly_total
def top_up(amount):
"""Esegui una ricarica."""
resp = requests.post(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/top-up",
headers={
"Authorization": f"Bearer {MGMT_KEY}",
"Content-Type": "application/json"
},
json={"amount": amount}
)
return resp.status_code == 200
# Logica di ricarica
balance = get_balance()
monthly_spent = get_monthly_top_ups()
if balance < MIN_BALANCE:
remaining_budget = MAX_MONTHLY - monthly_spent
if remaining_budget >= TOP_UP_AMOUNT:
if top_up(TOP_UP_AMOUNT):
print(f"Ricarica di ${TOP_UP_AMOUNT:.2f}. Nuovo saldo stimato: ${balance + TOP_UP_AMOUNT:.2f}")
else:
print("Errore durante la ricarica")
else:
print(f"Tetto mensile raggiunto (${monthly_spent:.2f} / ${MAX_MONTHLY:.2f})")
else:
print(f"Saldo sufficiente: ${balance:.2f}")
Previsione dei consumi
La previsione trasforma il monitoraggio in anticipazione. Una media su sette giorni è sufficiente per la maggior parte dei casi d’uso; ti fornisce una data di esaurimento, dandoti così il tempo di agire. Fai però attenzione alla stagionalità del tuo traffico: una media calcolata su una settimana lenta promette un’autonomia che svanirà non appena il traffico aumenterà.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Consumo negli ultimi 7 giorni
end = datetime.now()
start = end - timedelta(days=7)
usage_resp = requests.post(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/usage",
headers={
"Authorization": f"Bearer {MGMT_KEY}",
"Content-Type": "application/json"
},
json={
"analyticsRequest": {
"timeRange": {
"startTime": start.strftime("%Y-%m-%d %H:%M:%S"),
"endTime": end.strftime("%Y-%m-%d %H:%M:%S"),
"timezone": "Europe/Paris"
},
"timeUnit": "DAY",
"values": [{"name": "cost", "aggregation": "SUM"}]
}
}
)
# Calcola la media giornaliera
data_points = usage_resp.json().get("dataPoints", [])
daily_costs = [p.get("value", 0) for p in data_points]
avg_daily_cost = sum(daily_costs) / len(daily_costs) if daily_costs else 0
# Stima i giorni rimanenti
balance_resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
current_balance = balance_resp.json().get("balance", 0)
if avg_daily_cost > 0:
days_remaining = current_balance / avg_daily_cost
exhaustion_date = datetime.now() + timedelta(days=days_remaining)
print(f"Consumo medio: ${avg_daily_cost:.2f}/giorno")
print(f"Saldo corrente: ${current_balance:.2f}")
print(f"Esaurimento stimato: {exhaustion_date.strftime('%m/%d/%Y')} ({days_remaining:.0f} giorni)")
Dashboard di monitoraggio integrata
La dashboard riunisce ciò che tre diversi endpoint sanno sui tuoi costi: il saldo prepagato, gli addebiti di fatturazione mensili e i limiti configurati. Separati, ognuno racconta una storia incompleta: un saldo confortevole non dice nulla sul consumo postpagato che corre in parallelo. È la riconciliazione a fornire il costo reale del mese corrente.
#!/bin/bash
echo "=== Dashboard xAI - $(date '+%m/%d/%Y %H:%M') ==="
# Saldo prepagato
BALANCE=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('balance', 'N/A'))")
echo "Saldo prepagato: \$${BALANCE}"
# Addebiti postpagati
POSTPAID=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('totalAmount', 'N/A'))")
echo "Addebiti postpagati: \$${POSTPAID}"
# Limite di spesa
LIMIT=$(curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -c "import sys,json; print(json.load(sys.stdin).get('monthlyLimit', 'N/A'))")
echo "Limite mensile: \$${LIMIT}"
Punti chiave
- Automatizza le ricariche con una soglia minima e un tetto mensile
- Usa le analisi per prevedere le date di esaurimento del credito
- Combina saldo prepagato, addebiti postpagati e limiti in una dashboard unificata
- I crediti non sono rimborsabili: calibra le ricariche automatiche con cautela
- Integra questi script nel tuo cron o nella pipeline CI/CD