Limites de dépenses — Management API : clés & facturation

Contrôler vos coûts API

Les limites de dépenses (spending limits) sont votre filet de sécurité financier. Elles définissent un plafond au-delà duquel les requêtes API seront refusées, évitant les mauvaises surprises en fin de mois. La Management API permet de consulter et définir ces limites de manière programmatique.

Consulter les limites actuelles

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

La réponse donne le plafond du cycle en cours et la consommation actuelle — donc, par différence, votre marge. C’est le seul chiffre qui compte au quotidien : un plafond sans consommation associée ne dit pas si vous êtes à 10 % ou à 95 % du budget.

Définir des 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
  }'

Comportement au dépassement

Le point rassurant, et il mérite d’être dit explicitement : atteindre la limite ne produit jamais de surfacturation. Les requêtes sont refusées, pas facturées au-delà. Le risque se déplace donc du financier vers la disponibilité — ce qui est exactement ce que l’on veut, car une panne se diagnostique et se corrige en minutes, là où une facture inattendue se découvre trop tard.

Lorsque la consommation atteint la limite définie :

Les requêtes API sont refusées avec un code d’erreur spécifique
Les clés API restent actives mais les appels d’inférence échouent
La limite se réinitialise au début du cycle de facturation suivant

Stratégie de limites par environnement

Pour une équipe avec plusieurs projets, la limite doit refléter le risque propre à chaque environnement. En développement, le danger typique est la boucle de requêtes accidentelle — un script de test qui tourne toute la nuit — et une limite basse de 50 à 100 $ transforme cette erreur en incident à dix euros plutôt qu’en mauvaise surprise à mille. Le staging accueille les tests de charge, qui consomment légitimement plus : une limite modérée de 200 à 500 $ laisse la place aux campagnes de test tout en gardant un garde-fou. La production, elle, ne doit jamais être bridée au point de refuser des requêtes clients : une limite plus élevée (1 000 $ et au-delà, selon votre trafic) s’accompagne d’un monitoring actif — c’est l’alerte qui protège, la limite n’étant que le filet de dernier recours.

Aperçu des charges en cours

Pour savoir où vous en êtes dans le cycle actuel :

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

Cet endpoint retourne les charges accumulées depuis le début du cycle. Rapporté au nombre de jours écoulés, il donne mieux qu’un état des lieux : une projection. Une consommation de 40 % du budget au tiers du mois est saine ; les mêmes 40 % au dixième du mois annoncent un dépassement, et vous avez encore vingt-sept jours pour agir.

Automatiser le suivi des coûts

Script d’alerte de seuil

import requests

MANAGEMENT_API = "https://management-api.x.ai"
MGMT_KEY = "xai-mgmt-..."
TEAM_ID = "team-..."
ALERT_THRESHOLD = 0.80  # Alerte à 80% de la limite

# Récupérer la 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)

# Récupérer la consommation actuelle
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)

# Vérifier le seuil
if monthly_limit > 0:
    ratio = current_spend / monthly_limit
    if ratio >= ALERT_THRESHOLD:
        print(f"ALERTE : {ratio*100:.1f}% de la limite atteint")
        print(f"  Consommation : ${current_spend:.2f} / ${monthly_limit:.2f}")
        # Envoyer une notification

Intégration avec le monitoring

Combinez l’aperçu des charges avec votre solution de monitoring (Grafana, Datadog, etc.) pour créer des dashboards de coûts en temps réel :

# Récupérer le montant actuel pour l'envoyer à votre système de métriques
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

Ajuster les limites dynamiquement

La limite n’est pas gravée dans le marbre du cycle de facturation — et c’est une bonne chose, car la vie d’un produit ne suit pas le calendrier comptable. Avant un pic de trafic prévu, lancement produit ou campagne marketing, augmentez temporairement la limite : rien de pire qu’une campagne payante qui envoie des utilisateurs vers un service dont l’API refuse les requêtes pour cause de plafond atteint. À l’inverse, si le budget du mois est déjà entamé plus vite que prévu, abaisser la limite pour le reste du cycle transforme une dérive en contrainte maîtrisée. Le cas le plus critique reste l’incident de coûts — une boucle en production, un abus détecté : réduire immédiatement la limite est votre bouton d’arrêt d’urgence, celui qui stoppe l’hémorragie pendant que vous cherchez la cause.

# Augmenter temporairement pour un lancement
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}'

# Remettre la limite normale après le pic
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}'

Points clés à retenir

GET et POST sur /v1/billing/teams/{teamId}/postpaid/spending-limits pour consulter et définir les limites
Au dépassement de la limite, les requêtes API sont refusées (pas de surfacturation)
L’aperçu des charges (invoice/preview) permet de suivre la consommation en temps réel
Automatisez les alertes de seuil pour anticiper les dépassements
Adaptez les limites par environnement (dev, staging, production)