Crédits prépayés — Management API : clés & facturation

Le modèle prépayé de xAI

Les crédits prépayés vous permettent d’acheter un solde à l’avance, consommé au fil de vos appels API. Ce modèle est idéal pour contrôler vos dépenses : vous ne dépensez que ce que vous avez acheté, sans surprise en fin de mois. Les crédits sont utilisés en priorité avant la facturation mensuelle.

Consulter le solde

Le prépayé inverse le rapport au risque par rapport à la facturation mensuelle. En postpaid, vous découvrez le montant à la fin ; en prépayé, le plafond est posé d’avance et le pire scénario est une interruption de service — désagréable, mais borné. Pour une équipe qui découvre l’API ou un projet au budget arrêté, c’est le bon défaut.

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

La réponse contient :

Le solde actuel en dollars
L’historique des recharges (top-ups) avec dates et montants
L’historique de consommation par période

Acheter des crédits (top-up)

Pour recharger votre solde de crédits :

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

Points importants sur les crédits

Les quatre points ci-dessous ont des conséquences très concrètes sur la façon dont on automatise. Le second surtout : des crédits ne se remboursent pas. Cela suffit à disqualifier la stratégie du gros achat unique « pour être tranquille » — mieux vaut des recharges modestes et fréquentes, quitte à les automatiser, qu’une avance immobilisée sur un projet qui peut changer de direction.

Les crédits sont facturés immédiatement au moment de l’achat sur votre moyen de paiement par défaut
Les crédits prépayés ne sont pas remboursables (sauf obligation légale dans votre juridiction)
Les crédits sont consommés en priorité avant la facturation mensuelle postpaid
Il n’y a pas de date d’expiration mentionnée pour les crédits — ils restent disponibles tant qu’ils ne sont pas consommés

Flux de facturation avec crédits

L’ordre de consommation mérite d’être connu avant de configurer quoi que ce soit, car il détermine ce que voit chacun de vos tableaux de bord. Les crédits partent en premier, la facturation mensuelle prend le relais ensuite : autrement dit, un solde prépayé qui stagne à zéro pendant que tout fonctionne signifie que vous êtes déjà passé en postpaid sans vous en apercevoir.

Crédits prépayés disponibles : les tokens sont déduits du solde prépayé
Crédits épuisés : la consommation bascule en facturation mensuelle (postpaid)
Limite de dépenses atteinte : les requêtes sont refusées

Stratégies d’utilisation des crédits

Budget fixe mensuel

C’est la stratégie du budget dur : sans facturation mensuelle activée, l’épuisement des crédits arrête les appels au lieu de générer une dette. Assumez-en la contrepartie — le service s’interrompt, et il vaut mieux que ce soit un choix explicite qu’une découverte un vendredi soir. Combinez-la avec l’alerte de solde bas décrite plus loin.

import requests
from datetime import datetime

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

# Vérifier le solde
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)

# Recharger si le solde est bas
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"Rechargé de ${top_up_amount:.2f}")

Provision pour un projet

Provisionner par projet a un avantage qui dépasse la comptabilité : le solde devient une mesure d’avancement. Si la moitié des crédits est consommée alors qu’un quart du travail est fait, l’information arrive avant la fin, quand il est encore temps d’arbitrer entre réduire le périmètre ou changer de modèle.

# Budget projet : 500 $ sur 3 mois
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}'

Surveillez ensuite la consommation via les analytics (leçon suivante) pour vous assurer que le budget est respecté.

Suivi du solde

Alerte de solde bas

#!/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 "ALERTE : solde prépayé bas ($BALANCE $)"
    # Envoyer une notification
fi

Dashboard de consommation

Combinez le solde prépayé avec l’aperçu des charges postpaid pour avoir une vue complète de vos coûts :

# Solde prépayé
echo "=== Crédits prépayés ==="
curl -s "https://management-api.x.ai/v1/billing/teams/$TEAM_ID/prepaid/balance" \
  -H "Authorization: Bearer $MANAGEMENT_API_KEY" | python3 -m json.tool

# Charges postpaid en cours
echo "=== Charges postpaid ==="
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

Points clés à retenir

GET /v1/billing/teams/{teamId}/prepaid/balance retourne le solde et l’historique
POST /v1/billing/teams/{teamId}/prepaid/top-up achète des crédits (facturés immédiatement)
Les crédits prépayés ne sont pas remboursables
Les crédits sont consommés en priorité avant la facturation mensuelle
Automatisez les recharges avec un seuil minimum pour éviter les interruptions
Combinez crédits prépayés et limites de dépenses pour un contrôle total des coûts