Saldo e recargas automáticas
Nesta página
Monitorizar e automatizar recargas
Combinar o acompanhamento do saldo pré-pago com a análise de utilização permite configurar um sistema de recarga inteligente. Em vez de efetuar recargas manualmente, pode automatizar o processo com base em limiares e previsões de consumo.
Verificar detalhes do saldo
O endpoint devolve dois elementos que não deve confundir: o saldo instantâneo e o histórico de transações. O primeiro responde à pergunta «Ainda posso chamar a API?», enquanto o segundo responde a «A que velocidade estou a consumir?». É este segundo elemento que lhe permite antecipar e, portanto, o único no qual pode basear a automação.
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
A resposta contém o saldo atual e o histórico de transações (compras e consumo).
Sistema de recarga automática
Um sistema de recarga automática bem configurado depende de dois valores, sendo que um deles é frequentemente esquecido. O limiar de acionamento deve cobrir o seu consumo durante o tempo de reação: se verificar uma vez por dia, precisa de pelo menos um dia de crédito de antecedência; caso contrário, a automação será acionada após o corte. O limite mensal é a salvaguarda que falta na maioria das vezes — sem ele, um loop defeituoso na sua aplicação pode desencadear recargas sucessivas, e os créditos xAI não são reembolsáveis.
Estes dois valores não são definidos arbitrariamente: a próxima secção mostra como calculá-los com base no seu consumo real.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Configuration
MIN_BALANCE = 50.00 # Top-up threshold
TOP_UP_AMOUNT = 200.00 # Top-up amount
MAX_MONTHLY = 1000.00 # Monthly cap
def get_balance():
"""Get the current prepaid balance."""
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():
"""Calculate the total top-ups for the current month."""
resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
# Filter transactions for the current month
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):
"""Perform a top-up."""
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
# Top-up logic
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"Top-up of ${TOP_UP_AMOUNT:.2f}. Estimated new balance: ${balance + TOP_UP_AMOUNT:.2f}")
else:
print("Error during top-up")
else:
print(f"Monthly cap reached (${monthly_spent:.2f} / ${MAX_MONTHLY:.2f})")
else:
print(f"Sufficient balance: ${balance:.2f}")
Previsão de consumo
A previsão transforma a monitorização em antecipação. Uma média de sete dias é suficiente para a maioria dos casos de uso; fornece-lhe uma data de esgotamento, dando-lhe tempo para agir. Tenha apenas cuidado com a sazonalidade do seu próprio tráfego — uma média calculada numa semana de baixa atividade promete uma autonomia que desaparecerá assim que o tráfego aumentar.
import requests
from datetime import datetime, timedelta
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Consumption over the last 7 days
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"}]
}
}
)
# Calculate daily average
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
# Estimate remaining days
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"Average consumption: ${avg_daily_cost:.2f}/day")
print(f"Current balance: ${current_balance:.2f}")
print(f"Estimated exhaustion: {exhaustion_date.strftime('%m/%d/%Y')} ({days_remaining:.0f} days)")
Painel de acompanhamento integrado
O painel reúne o que três endpoints diferentes sabem sobre os seus custos: o saldo pré-pago, as faturas mensais pós-pagas e os limites configurados. Separadamente, cada um conta uma história incompleta — um saldo confortável nada diz sobre o consumo pós-pago a ocorrer em paralelo. É a reconciliação que fornece o custo real do mês corrente.
#!/bin/bash
echo "=== xAI Dashboard - $(date '+%m/%d/%Y %H:%M') ==="
# Prepaid balance
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 "Prepaid balance: \$${BALANCE}"
# Postpaid charges
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 "Postpaid charges: \$${POSTPAID}"
# Spending limit
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 "Monthly limit: \$${LIMIT}"
Pontos-chave
- Automatize as recargas com um limiar mínimo e um limite mensal
- Utilize a análise de dados para prever as datas de esgotamento do crédito
- Combine o saldo pré-pago, as cobranças pós-pagas e os limites num painel unificado
- Os créditos não são reembolsáveis — calibre as recargas automáticas com cautela
- Integre estes scripts no seu cron ou pipeline de CI/CD