Créditos pré-pagos
Nesta página
Modelo pré-pago da xAI
Os créditos pré-pagos permitem-lhe adquirir um saldo antecipadamente, que é consumido à medida que efetua chamadas à API. Este modelo é ideal para controlar despesas: só gasta o que comprou, sem surpresas no final do mês. Os créditos são utilizados antes da faturação mensal.
Consultar o seu saldo
O pré-pago inverte a relação de risco em comparação com a faturação mensal. No pós-pago, descobre o valor no final; no pré-pago, o limite é definido antecipadamente e o pior cenário é a interrupção do serviço — desagradável, mas delimitado. Para uma equipa que está a explorar a API ou para um projeto com um orçamento fixo, esta é a compensação correta.
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 em dólares
- O histórico de recargas com datas e valores
- O histórico de utilização por período
Comprar créditos (recarga)
Para recarregar o seu saldo de créditos:
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/top-up" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"amount": 100.00
}'
Pontos importantes sobre os créditos
Os quatro pontos abaixo têm consequências concretas na forma como automatiza os seus processos. O segundo, em especial: os créditos não são reembolsáveis. Isto, por si só, invalida a estratégia de uma única compra avultada “por segurança”; recargas modestas e frequentes são preferíveis, mesmo que as automatize, do que capital imobilizado num projeto que pode mudar de direção.
- Os créditos são cobrados imediatamente no momento da compra, no seu método de pagamento predefinido
- Os créditos pré-pagos não são reembolsáveis (salvo exigência legal na sua jurisdição)
- Os créditos são consumidos prioritariamente antes da faturação mensal pós-paga
- Não existe data de expiração listada para os créditos; estes permanecem disponíveis até serem consumidos
Fluxo de faturação com créditos
Vale a pena conhecer a ordem de consumo antes de configurar qualquer coisa, pois determina o que cada um dos seus painéis mostra. Os créditos vêm primeiro, a faturação mensal assume o controlo depois: por outras palavras, um saldo pré-pago estagnado em zero enquanto tudo funciona significa que já mudou para o pós-pago sem se aperceber.
- Créditos pré-pagos disponíveis: os tokens são deduzidos do saldo pré-pago
- Créditos esgotados: o consumo muda para a faturação mensal (pós-pago)
- Limite de despesas atingido: os pedidos são recusados
Estratégias de utilização de créditos
Orçamento mensal fixo
Esta é a estratégia de orçamento rígido: sem a faturação mensal ativada, o esgotamento dos créditos interrompe as chamadas em vez de gerar dívida. Aceite a compensação — o serviço é interrompido, e é preferível que isto seja uma escolha explícita do que uma descoberta numa sexta-feira à noite. Combine isto com o alerta de saldo baixo descrito mais adiante.
import requests
from datetime import datetime
MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
# Verificar saldo
balance_resp = requests.get(
f"{MANAGEMENT_API}/v1/billing/teams/{TEAM_ID}/prepaid/balance",
headers={"Authorization": f"Bearer {MGMT_KEY}"}
)
balance = balance_resp.json().get("balance", 0)
# Recarregar se o saldo estiver baixo
MONTHLY_BUDGET = 200.00
RECHARGE_THRESHOLD = 50.00
if balance < RECHARGE_THRESHOLD:
top_up_amount = MONTHLY_BUDGET - balance
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": top_up_amount}
)
print(f"Recarregado ${top_up_amount:.2f}")
Provisionamento de projetos
O provisionamento de projetos tem uma vantagem para além da contabilidade: o saldo torna-se uma medida de progresso. Se metade dos créditos for consumida enquanto apenas um quarto do trabalho está feito, obtém essa informação antes do fim, quando ainda há tempo para decidir se reduz o âmbito ou muda de modelos.
# Orçamento do projeto: 500 $ durante 3 meses
curl -X POST "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/top-up" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"amount": 500.00}'
De seguida, monitore a utilização através da análise de dados (próxima lição) para garantir que o orçamento é respeitado.
Monitorização do saldo
Alerta de saldo baixo
#!/bin/bash
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', 0))")
THRESHOLD=20.00
if (( $(echo "$BALANCE < $THRESHOLD" | bc -l) )); then
echo "ALERTA: saldo pré-pago baixo ($BALANCE $)"
# Enviar uma notificação
fi
Painel de utilização
Combine o saldo pré-pago com a pré-visualização das cobranças pós-pagas para ter uma visão completa dos seus custos:
# Saldo pré-pago
echo "=== Créditos Pré-pagos ==="
curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool
# Cobranças pós-pagas atuais
echo "=== Cobranças Pós-pagas ==="
curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/postpaid/invoice/preview" \
-H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool
Pontos-chave
GET /v1/billing/teams/{teamId}/prepaid/balancedevolve o saldo e o históricoPOST /v1/billing/teams/{teamId}/prepaid/top-upcompra créditos (cobrados imediatamente)- Os créditos pré-pagos não são reembolsáveis
- Os créditos são consumidos antes da faturação mensal
- Automatize as recargas com um limite mínimo para evitar interrupções
- Combine créditos pré-pagos e limites de despesas para um controlo total de custos