Vai al contenuto principale
Italiano— Scegli una lingua
Menu

Crediti prepagati

Lezione 8 di 14 Aggiornata il 29 luglio 2026 Sviluppatore
In questa pagina
  1. Modello prepagato xAI
  2. Controlla il tuo saldo
  3. Acquista crediti (ricarica)
  4. Strategie di utilizzo dei crediti
  5. Monitoraggio del saldo
  6. Punti chiave

Modello prepagato xAI

I crediti prepagati ti permettono di acquistare un saldo anticipato, che viene consumato man mano che effettui chiamate API. Questo modello è ideale per controllare la spesa: spendi solo ciò che hai acquistato, senza sorprese a fine mese. I crediti vengono utilizzati prima della fatturazione mensile.

Controlla il tuo saldo

Il prepagato ribalta il rapporto di rischio rispetto alla fatturazione mensile. Con il postpagato, scopri l’importo alla fine; con il prepagato, il tetto è stabilito in anticipo e lo scenario peggiore è l’interruzione del servizio: spiacevole, ma delimitato. Per un team che esplora l’API o un progetto con un budget fisso, questo è il compromesso giusto.

curl "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY"

La risposta contiene:

  • Il saldo corrente in dollari
  • La cronologia dei ricarichi con date e importi
  • La cronologia dell’utilizzo per periodo

Acquista crediti (ricarica)

Per ricaricare il tuo saldo di crediti:

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
  }'

Punti importanti sui crediti

I quattro punti seguenti hanno conseguenze concrete sul modo in cui automatizzi i processi. Il secondo in particolare: i crediti non sono rimborsabili. Questo da solo esclude la strategia di un unico grande acquisto “per sicurezza”: ricariche modeste e frequenti sono migliori, anche se le automatizzi, rispetto al capitale bloccato in un progetto che potrebbe cambiare direzione.

  • I crediti vengono addebitati immediatamente al momento dell’acquisto sul tuo metodo di pagamento predefinito
  • I crediti prepagati sono non rimborsabili (salvo obbligo di legge nella tua giurisdizione)
  • I crediti vengono consumati in priorità rispetto alla fatturazione mensile postpagata
  • Non è indicata alcuna data di scadenza per i crediti: rimangono disponibili fino al consumo

Flusso di fatturazione con i crediti

Vale la pena conoscere l’ordine di consumo prima di configurare qualsiasi cosa, poiché determina cosa mostrano i tuoi dashboard. I crediti vanno per primi, la fatturazione mensile subentra dopo: in altre parole, un saldo prepagato fermo a zero mentre tutto funziona significa che sei già passato al postpagato senza accorgertene.

  1. Crediti prepagati disponibili: i token vengono detratti dal saldo prepagato
  2. Crediti esauriti: il consumo passa alla fatturazione mensile (postpagato)
  3. Limite di spesa raggiunto: le richieste vengono rifiutate

Strategie di utilizzo dei crediti

Budget mensile fisso

Questa è la strategia del budget rigido: senza la fatturazione mensile abilitata, l’esaurimento dei crediti interrompe le chiamate invece di generare debito. Accetta il compromesso: il servizio si interrompe, ed è meglio che sia una scelta esplicita piuttosto che una scoperta il venerdì sera. Combinala con l’avviso di saldo basso descritto più avanti.

import requests
from datetime import datetime

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."

# Controlla il 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)

# Ricarica se il saldo è basso
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"Ricaricati ${top_up_amount:.2f}")

Provisioning del progetto

Il provisioning del progetto ha un vantaggio che va oltre la contabilità: il saldo diventa una misura dei progressi. Se metà dei crediti sono stati consumati mentre è stato completato solo un quarto del lavoro, ricevi l’informazione prima della fine, quando c’è ancora tempo per decidere se ridurre lo scopo o cambiare modello.

# Budget di progetto: $500 su 3 mesi
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}'

Quindi monitora l’utilizzo tramite gli analytics (prossima lezione) per assicurarti che il budget venga rispettato.

Monitoraggio del saldo

Avviso di saldo basso

#!/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 "ALLARME: saldo prepagato basso ($BALANCE $)"
    # Invia una notifica
fi

Dashboard di utilizzo

Combina il saldo prepagato con l’anteprima degli addebiti postpagati per una visione completa dei tuoi costi:

# Saldo prepagato
echo "=== Crediti Prepagati ==="
curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

# Addebiti postpagati correnti
echo "=== Addebiti Postpagati ==="
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

Punti chiave

  • GET /v1/billing/teams/{teamId}/prepaid/balance restituisce il saldo e la cronologia
  • POST /v1/billing/teams/{teamId}/prepaid/top-up acquista crediti (addebitati immediatamente)
  • I crediti prepagati sono non rimborsabili
  • I crediti vengono consumati prima della fatturazione mensile
  • Automatizza le ricariche con una soglia minima per evitare interruzioni
  • Combina crediti prepagati e limiti di spesa per il controllo totale dei costi