Headers API et gestion des dépassements

Contrôler le routage des requêtes

Le débit provisionné ne se limite pas à une simple réservation de capacité. L’API xAI fournit des headers HTTP spécifiques qui vous permettent de contrôler finement le routage de chaque requête entre votre capacité dédiée et le pool partagé.

Le header x-pt-disable

Le header x-pt-disable permet de contourner volontairement votre capacité provisionnée pour une requête donnée :

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-1-fast-reasoning",
    "messages": [{"role": "user", "content": "Résumez ce document."}]
  }'

Cas d’utilisation de x-pt-disable

• Tâches non critiques : des analyses batch ou des traitements différés qui n’ont pas besoin de la garantie de latence
• Préservation de la capacité : libérer votre allocation pour les requêtes prioritaires pendant les pics d’activité
• Tests A/B : comparer les performances entre capacité dédiée et capacité partagée
• Débogage : isoler un problème lié à la capacité provisionnée

Le header x-pt-id

Le header x-pt-id permet de router une requête vers un pool de capacité spécifique :

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-1-fast-reasoning",
    "messages": [{"role": "user", "content": "Comment puis-je vous aider ?"}]
  }'

Organiser vos pools de capacité

Si votre organisation a plusieurs applications utilisant l’API Grok, vous pouvez créer des pools séparés pour :

• pool-support : capacité dédiée au chatbot de support client
• pool-analyse : capacité pour l’analyse documentaire
• pool-interne : capacité pour les outils internes

Cette segmentation permet de :

• Isoler les performances entre applications
• Suivre la consommation par usage
• Éviter qu’une application ne monopolise la capacité au détriment d’une autre

Gestion des dépassements

Lorsque vos requêtes dépassent la capacité provisionnée, le comportement est automatique et transparent :

Ce qui se passe en cas de dépassement

1. La requête est automatiquement redirigée vers le pool partagé (pay-as-you-go)
2. Les tarifs standard du modèle s’appliquent pour cette requête
3. La requête est soumise aux limites de débit standard (rate limits)
4. Aucune erreur n’est retournée : le basculement est transparent pour votre application

Implications pratiques

• Votre application ne subira jamais d’erreur 429 (rate limit) due à un dépassement de capacité provisionnée
• Le coût de la requête sera facturé au tarif pay-as-you-go, potentiellement plus élevé
• Les temps de réponse peuvent varier car la requête est traitée sur l’infrastructure partagée
• Le SLA 99.9% ne couvre que les requêtes traitées dans le cadre du débit provisionné

Surveiller les dépassements

La Management API vous permet de suivre la proportion de requêtes traitées en mode provisionné vs pay-as-you-go. Si vous observez un taux de dépassement élevé, c’est le signe qu’il faut augmenter votre allocation.

Intégration dans votre code

Une stratégie courante consiste à catégoriser vos requêtes par priorité :

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-1-fast-reasoning",
            "messages": [{"role": "user", "content": prompt}],
        },
    )
    return response.json()

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