Limites de Despesa
Nesta página
Controlo dos Custos da API
Os limites de despesa são a sua rede de segurança financeira. Estabelecem um teto além do qual os pedidos à API são recusados, evitando cobranças inesperadas no final do mês. A Management API permite-lhe visualizar e definir estes limites programaticamente.
Visualizar Limites Atuais
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
A resposta mostra o teto atual do ciclo e o seu consumo corrente — logo, por diferença, a sua margem restante. Este é o único número que importa no dia a dia: um teto sem dados de consumo não lhe indica se está a 10% ou a 95% do seu orçamento.
Definir Limites
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"monthlyLimit": 500.00
}'
Comportamento ao Atingir o Limite
Eis a parte tranquilizadora, que vale a pena explicitar: atingir o limite nunca resulta em sobrefaturação. Os pedidos são recusados, não faturados além do teto. O risco desloca-se do financeiro para a disponibilidade — que é exatamente o que pretende, pois uma indisponibilidade é diagnosticada e resolvida em minutos, enquanto uma fatura inesperada só é detetada tarde demais.
Quando o consumo atinge o limite definido:
- Os pedidos à API são recusados com um código de erro específico
- As chaves da API permanecem ativas, mas as chamadas de inferência falham
- O limite repõe-se no início do próximo ciclo de faturação
Estratégia de Limites por Ambiente
Para uma equipa com múltiplos projetos, o limite deve refletir o risco específico de cada ambiente. No desenvolvimento, o perigo típico é um loop acidental de pedidos — um script de teste a correr a noite toda — e um limite baixo de 50 $ a 100 $ transforma esse erro num incidente de 10 $ em vez de uma surpresa de 1 000 $. O ambiente de staging gere testes de carga, que consomem legitimamente mais: um limite moderado de 200 $ a 500 $ deixa espaço para campanhas de teste mantendo uma salvaguarda. A produção, contudo, nunca deve ser estrangulada a ponto de recusar pedidos de clientes: um limite mais elevado (1 000 $ e além, dependendo do seu tráfego) vem acompanhado de monitorização ativa — o alerta protege-o, enquanto o limite é apenas a rede de segurança de último recurso.
Visualizar Encargos Atuais
Para saber onde se encontra no ciclo atual:
curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY"
Este endpoint devolve os encargos acumulados desde o início do ciclo. Comparado com o número de dias decorridos, oferece mais do que uma instantânea: uma projeção. Consumir 40% do orçamento num terço do mês é saudável; os mesmos 40% num décimo do mês sinalizam um excesso, e ainda tem vinte e sete dias para agir.
Automatizar a Monitorização de Custos
Script de Alerta de Limiar
import requests
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
ALERT_THRESHOLD = 0.80 # Alerta a 80% do limite
# Obter o limite
limits_resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/postpaid/spending-limits",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
monthly_limit = limits_resp.json().get("monthlyLimit", 0)
# Obter consumo atual
preview_resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/postpaid/invoice/preview",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
current_spend = preview_resp.json().get("totalAmount", 0)
# Verificar limiar
if monthly_limit > 0:
ratio = current_spend / monthly_limit
if ratio >= ALERT_THRESHOLD:
print(f"ALERTA: {ratio*100:.1f}% do limite atingido")
print(f" Despesa: ${current_spend:.2f} / ${monthly_limit:.2f}")
# Enviar notificação
Integração com Monitorização
Combine a pré-visualização dos encargos com a sua solução de monitorização (Grafana, Datadog, etc.) para criar painéis de custos em tempo real:
# Obter valor atual para enviar ao seu sistema de métricas
CURRENT_SPEND=$(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', 0))")
echo "xai.billing.current_spend:$CURRENT_SPEND|g" | nc -u -w1 localhost 8125
Ajustar Limites Dinamicamente
O limite não está definido de forma imutável para o ciclo de faturação — e isso é positivo, pois o ciclo de vida do produto não segue o calendário contabilístico. Antes de um pico de tráfego esperado, lançamento de produto ou campanha de marketing, aumente temporariamente o limite: nada pior do que uma campanha paga enviar utilizadores para um serviço cuja API recusa pedidos devido a um teto atingido. Por outro lado, se o orçamento do mês já foi gasto mais rapidamente do que o previsto, reduzir o limite para o restante ciclo transforma um desvio numa restrição controlada. O caso mais crítico permanece um incidente de custos — um loop em produção, abuso detetado: baixar o limite imediatamente é o seu botão de emergência, aquele que estanca a sangria enquanto procura a causa.
# Aumentar temporariamente para um lançamento
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"monthlyLimit": 2000.00}'
# Repor o limite normal após o pico
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/spending-limits" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"monthlyLimit": 500.00}'
Pontos-chave
- Utilize
GETePOSTem/v1/billing/teams/{teamId}/postpaid/spending-limitspara visualizar e definir limites - Quando o limite é excedido, os pedidos à API são recusados (sem sobrefaturação)
- A pré-visualização dos encargos (
invoice/preview) permite acompanhar o consumo em tempo real - Automatize alertas de limiar para antecipar excessos
- Adapte os limites por ambiente (dev, staging, production)