Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Limites de Despesa

Aula 7 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Controlo dos Custos da API
  2. Visualizar Limites Atuais
  3. Definir Limites
  4. Visualizar Encargos Atuais
  5. Automatizar a Monitorização de Custos
  6. Ajustar Limites Dinamicamente
  7. Pontos-chave

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 GET e POST em /v1/billing/teams/{teamId}/postpaid/spending-limits para 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)