Saldo y recargas automáticas
En esta página
Supervisión y automatización de recargas
Combinar el seguimiento del saldo prepago con análisis de uso te permite configurar un sistema de recarga inteligente. En lugar de realizar recargas manuales, puedes automatizar el proceso basándote en umbrales y previsiones de consumo.
Consulta de detalles del saldo
El endpoint devuelve dos elementos que no debes confundir: el saldo instantáneo y el historial de transacciones. El primero responde a «¿Puedo seguir llamando a la API?»; el segundo, a «¿A qué velocidad estoy consumiendo?». Este segundo es el que te permite anticiparte y, por tanto, el único sobre el que puedes basar la automatización.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
La respuesta contiene el saldo actual y el historial de transacciones (compras y consumo).
Sistema de recarga automática
Una recarga automática bien configurada depende de dos cifras, y una de ellas se olvida con frecuencia. El umbral de activación debe cubrir tu consumo durante el tiempo de reacción: si compruebas el saldo una vez al día, necesitas al menos un día de crédito por adelantado; de lo contrario, la automatización se activará después del corte. El límite mensual es la salvaguarda que falta con más frecuencia: sin él, un bucle defectuoso en tu aplicación puede desencadenar recarga tras recarga, y los créditos de xAI no son reembolsables.
Estos dos valores no se establecen arbitrariamente: la siguiente sección muestra cómo calcularlos en función de tu consumo real.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Configuración
MIN_BALANCE = 50.00 # Umbral de recarga
TOP_UP_AMOUNT = 200.00 # Importe de la recarga
MAX_MONTHLY = 1000.00 # Límite mensual
def get_balance():
"""Obtiene el saldo prepago actual."""
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():
"""Calcula el total de recargas del mes en curso."""
resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
# Filtra las transacciones del mes actual
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):
"""Realiza una recarga."""
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
# Lógica de recarga
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"Recarga de ${TOP_UP_AMOUNT:.2f}. Saldo nuevo estimado: ${balance + TOP_UP_AMOUNT:.2f}")
else:
print("Error durante la recarga")
else:
print(f"Límite mensual alcanzado (${monthly_spent:.2f} / ${MAX_MONTHLY:.2f})")
else:
print(f"Saldo suficiente: ${balance:.2f}")
Previsión de consumo
La previsión convierte la supervisión en anticipación. Una media de siete días basta para la mayoría de los casos de uso; te proporciona una fecha de agotamiento, de modo que tienes tiempo para actuar. Eso sí, cuida con la estacionalidad de tu propio tráfico: una media calculada en una semana tranquila promete una autonomía que desaparecerá en cuanto el tráfico aumente.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Consumo de los últimos 7 días
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"}]
}
}
)
# Calcula la media diaria
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
# Estima los días restantes
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}/día")
print(f"Saldo actual: ${current_balance:.2f}")
print(f"Agotamiento estimado: {exhaustion_date.strftime('%m/%d/%Y')} ({days_remaining:.0f} días)")
Panel de seguimiento integrado
El panel reúne lo que tres endpoints distintos saben sobre tus costes: el saldo prepago, los cargos de facturación mensuales y los límites configurados. Por separado, cada uno cuenta una historia incompleta: un saldo holgado no dice nada sobre el consumo pospago que se ejecuta en paralelo. Es la conciliación la que ofrece el coste real del mes en curso.
#!/bin/bash
echo "=== Panel de xAI - $(date '+%m/%d/%Y %H:%M') ==="
# Saldo prepago
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 prepago: \$${BALANCE}"
# Cargos pospagos
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 "Cargos pospagos: \$${POSTPAID}"
# Límite de gasto
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 "Límite mensual: \$${LIMIT}"
Puntos clave
- Automatiza las recargas con un umbral mínimo y un límite mensual
- Usa análisis para prever fechas de agotamiento del crédito
- Combina saldo prepago, cargos pospagos y límites en un panel unificado
- Los créditos no son reembolsables: calibra las recargas automáticas con precaución
- Integra estos scripts en tu cron o en tu canalización de CI/CD