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

Créditos pré-pagos

Aula 8 de 14 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Modelo pré-pago da xAI
  2. Consultar o seu saldo
  3. Comprar créditos (recarga)
  4. Estratégias de utilização de créditos
  5. Monitorização do saldo
  6. Pontos-chave

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.

  1. Créditos pré-pagos disponíveis: os tokens são deduzidos do saldo pré-pago
  2. Créditos esgotados: o consumo muda para a faturação mensal (pós-pago)
  3. 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/balance devolve o saldo e o histórico
  • POST /v1/billing/teams/{teamId}/prepaid/top-up compra 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