Cache automatique de l'API

Le cache comme levier de réduction des coûts

Le cache automatique est le mécanisme qui pèse le plus lourd sur votre facture, dans un sens comme dans l’autre. Chez plusieurs fournisseurs, il faut le déclarer explicitement dans la requête, marquer les blocs à conserver et gérer leur durée de vie. xAI a fait un choix différent : le cache s’applique de lui-même à toutes les requêtes, sans paramètre ni annotation. Vous n’avez rien à activer, mais vous avez tout à gagner à comprendre ce qui le déclenche, car un prompt mal structuré n’en profite jamais et paie le tarif plein sur l’intégralité de son entrée.

Comment fonctionne le cache

Le cache opère sur les tokens d’entrée, et uniquement sur eux : la génération de la réponse est toujours facturée au tarif normal. Lorsque le début de votre prompt reproduit exactement le début d’un prompt déjà traité, la portion identique est servie depuis le cache au tarif réduit, et seule la partie nouvelle passe au tarif standard.

Trois familles d’applications en tirent un bénéfice immédiat. Une conversation, d’abord : le prompt système et tous les tours précédents sont rigoureusement identiques d’un appel au suivant, seule la dernière question change, si bien que le taux de cache monte mécaniquement à mesure que l’échange s’allonge. Un prompt à contexte fixe ensuite — un contrat, un manuel technique, un référentiel produit suivi d’une question variable — voit son bloc documentaire caché dès le deuxième appel. Un pipeline RAG, enfin, conserve des instructions système constantes ; seul le contexte récupéré change, et si vous le placez après les instructions, le préfixe reste cachable.

Sur la grille tarifaire de xAI, l’écart est considérable. Sur grok-4.3 et grok-4.20-0309, un million de tokens d’entrée cachés coûte $0.20 contre $1.25 au tarif standard. Sur grok-4.5, le même million revient à $0.30 au lieu de $2.00. Autrement dit, un préfixe stable de 5 000 tokens réutilisé mille fois par jour vous coûte cinq à sept fois moins cher qu’un prompt reconstruit à chaque appel — pour un résultat strictement identique.

Le header x-grok-conv-id

Pour aider l’infrastructure à rapprocher les requêtes qui vont ensemble, l’API accepte un header dédié :

curl -X POST "https://api.x.ai/v1/chat/completions" \
  -H "Authorization: Bearer $XAI_API_KEY" \
  -H "x-grok-conv-id: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "grok-4.20",
    "messages": [...]
  }'

Le header x-grok-conv-id attend un UUID v4. La règle d’usage est simple : un identifiant par conversation ou par flux de traitement, réutilisé pour tous les appels qui en font partie. Vous signalez ainsi que ces requêtes sont liées, ce qui augmente la probabilité de réutilisation du cache. L’erreur classique consiste à générer l’UUID au moment de l’appel plutôt qu’à l’ouverture de la session — chaque tour reçoit alors un identifiant différent et le bénéfice disparaît. Générez-le une fois, stockez-le avec l’état de la conversation :

import uuid

# Un UUID par conversation
conv_id = str(uuid.uuid4())

# Utiliser le même UUID pour tous les tours de la conversation
headers = {
    "Authorization": f"Bearer {api_key}",
    "x-grok-conv-id": conv_id,
    "Content-Type": "application/json"
}

Vérifier l’efficacité du cache

Rien ne remplace la mesure. Le champ cached_tokens de l’objet usage, vu à la leçon précédente, vous dit exactement ce qui a été servi depuis le cache :

{
  "usage": {
    "prompt_tokens": 5000,
    "cached_tokens": 4200,
    "completion_tokens": 300
  }
}

Ici, 4 200 tokens sur 5 000 proviennent du cache, soit un taux de 84 % ; seuls 800 tokens ont été facturés au tarif standard. Prenez l’habitude de relever ce ratio sur un échantillon de requêtes réelles après chaque mise en production : si vous constatez un taux proche de zéro sur une application conversationnelle, quelque chose varie en tête de prompt, et la leçon suivante vous montrera quoi.

Points clés à retenir

• Le cache est automatique : aucune configuration nécessaire
• Utilisez le header x-grok-conv-id avec un UUID v4 pour regrouper les requêtes liées
• Le champ cached_tokens dans l’objet usage indique le nombre de tokens servis depuis le cache
• L’entrée cachée coûte 5 à 7 fois moins cher : $0.20/M sur grok-4.3, $0.30/M sur grok-4.5
• Plus votre prompt est stable en début de séquence, plus le taux de cache sera élevé