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 indique le montant maximum autorisé pour le cycle de facturation en cours, ainsi que la consommation actuelle.

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

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, définissez des limites adaptées :

Développement : limite basse (50-100 $) pour éviter les boucles de requêtes accidentelles
Staging : limite modérée (200-500 $) pour les tests de charge
Production : limite plus élevée (1000 $ +) avec un monitoring actif

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 le montant total des charges accumulées depuis le début du cycle. Comparez-le à votre limite pour évaluer votre marge restante.

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

Dans certains cas, vous devrez ajuster les limites en cours de mois :

Pic de trafic prévu (lancement produit, campagne marketing) : augmentez temporairement la limite
Budget réduit : diminuez la limite pour le reste du mois
Incident de coûts : réduisez immédiatement la limite pour stopper l’hémorragie

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