Headers API et gestion des dépassements

Décider quelles requêtes consomment votre capacité

Réserver de la capacité ne règle que la moitié du problème : il reste à choisir quelles requêtes en profitent réellement. Le débit provisionné n’est donc pas une enveloppe achetée une fois pour toutes en début de mois, c’est un mécanisme que vous pilotez appel par appel. L’API xAI expose pour cela des headers HTTP dédiés qui arbitrent, requête par requête, entre votre capacité dédiée et le pool partagé. Une allocation figée devient ainsi un levier opérationnel que vos équipes manipulent directement depuis le code applicatif.

Contourner volontairement la capacité dédiée

Le premier header sert à écarter une requête de votre allocation :

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-disable: true" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "Résumez ce document."}]
  }'

Renoncer à sa propre capacité paraît contre-intuitif. Quatre situations le justifient pourtant au quotidien. Les tâches non critiques d’abord : une analyse batch lancée à vingt-deux heures ou un traitement différé n’a que faire d’une garantie de latence, et il serait dommage qu’elle grignote l’allocation payée pour le trafic interactif. La préservation de la capacité pendant les pics ensuite : en désactivant le débit provisionné sur les traitements secondaires, vous libérez l’allocation au moment précis où les requêtes prioritaires affluent. Le header sert aussi aux tests A/B, quand vous voulez mesurer l’écart réel de performance entre capacité dédiée et capacité partagée sur votre propre charge plutôt que sur une promesse commerciale. Il est enfin précieux en débogage : forcer le passage par le pool partagé vous dit immédiatement si l’anomalie observée vient de la capacité provisionnée ou de votre code.

Router une requête vers un pool précis

Le second header dirige l’appel vers un pool de capacité identifié :

curl https://api.x.ai/v1/chat/completions \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-pt-id: pool-support-client" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.3",
    "messages": [{"role": "user", "content": "Comment puis-je vous aider ?"}]
  }'

Ce header devient indispensable dès que plusieurs applications de la maison appellent Grok. Vous créez alors des pools séparés — un pool-support pour le chatbot de support client, un pool-analyse pour l’analyse documentaire, un pool-interne pour les outils métier — et chacun vit sa vie. La segmentation isole les performances : la campagne d’analyse documentaire lancée un lundi matin ne dégrade plus les temps de réponse du support. Elle produit aussi une consommation ventilée par usage, donc une base chiffrée pour refacturer ou arbitrer, là où l’on raisonnait auparavant à l’impression. Et elle interdit mécaniquement qu’une seule application monopolise la capacité au détriment des autres.

Ce qui se produit en cas de dépassement

Lorsque le trafic excède la capacité provisionnée, le basculement est automatique et silencieux : la requête part vers le pool partagé en pay-as-you-go, les tarifs standard du modèle s’appliquent, et elle est soumise aux limites de débit habituelles. Aucune erreur n’est retournée, votre application ne voit rien passer.

Cette discrétion a deux visages. Côté disponibilité, la nouvelle est bonne : vous ne rencontrerez jamais d’erreur 429 provoquée par un dépassement de capacité provisionnée. Côté finances et qualité de service, elle l’est moins. La requête est facturée au tarif pay-as-you-go, potentiellement plus élevé ; les temps de réponse peuvent varier puisque le traitement a lieu sur l’infrastructure partagée ; et surtout le SLA 99.9 % ne couvre que les requêtes traitées dans le cadre du débit provisionné. Un dépassement ne casse donc rien, il vous fait simplement sortir sans bruit du périmètre que vous payez. La Management API expose la proportion de requêtes traitées en mode provisionné par rapport au pay-as-you-go : examinez ce ratio chaque mois au même titre qu’une facture. Un taux de dépassement qui grimpe est le signal qu’il faut réviser l’allocation à la hausse.

Traduire la priorité dans le code applicatif

Plutôt que de multiplier les fonctions d’appel, la pratique la plus solide consiste à qualifier la priorité au moment même où la requête est émise :

import httpx

def query_grok(prompt: str, priority: str = "normal"):
    headers = {
        "Authorization": f"Bearer {API_KEY}",
        "Content-Type": "application/json",
    }

    if priority == "low":
        headers["x-pt-disable"] = "true"
    elif priority == "high":
        headers["x-pt-id"] = "pool-critique"

    response = httpx.post(
        "https://api.x.ai/v1/chat/completions",
        headers=headers,
        json={
            "model": "grok-4.3",
            "messages": [{"role": "user", "content": prompt}],
        },
    )
    return response.json()

Le paramètre priority devient la seule décision qui remonte au métier, et la politique de routage reste concentrée dans une fonction unique que l’on fait évoluer sans toucher au reste. Reprenez votre propre code d’appel et rangez chaque point d’entrée dans l’une des trois catégories : l’exercice montre régulièrement qu’une bonne moitié du trafic n’avait aucun besoin de capacité dédiée.

Points clés à retenir

• Le header x-pt-disable: true contourne la capacité provisionnée pour une requête
• Le header x-pt-id route vers un pool de capacité spécifique
• Les dépassements retombent automatiquement en pay-as-you-go sans erreur
• La segmentation en pools permet d’isoler les performances et de suivre la consommation par application
• Surveillez le taux de dépassement pour ajuster votre allocation si nécessaire