Prompt caching Claude API : 90 % d'économies en 1 header

Le 14 août 2024, Anthropic a rendu le prompt caching disponible en beta publique sur Claude 3.5 Sonnet et Claude 3 Haiku. L'annonce est sobre, mais les chiffres ne le sont pas : 90 % de réduction des coûts sur les tokens cachés, 85 % de latence en moins sur les prompts longs. Si tu intègres l'API Claude dans une application PHP — assistant documentaire, support client, pipeline de traitement de contenu — cette feature change radicalement le calcul économique sans toucher à ton architecture.

Ce que change le prompt caching pour tes coûts API

Le principe est simple : au lieu de renvoyer l'intégralité de ton prompt système à chaque requête, l'API conserve en mémoire les tokens identiques d'un appel à l'autre pendant 5 minutes. Les tokens lus depuis le cache ne coûtent que 10 % du prix normal. Concrètement, pour un prompt système de 5 000 tokens — documentation produit, règles métier, base de connaissance interne :

• Sans cache : 5 000 tokens × $3/MTok = $0,015 par appel (Claude 3.5 Sonnet)
• Avec cache en lecture : 5 000 tokens × $0,30/MTok = $0,0015 par appel — dix fois moins cher
• Cache write (première écriture ou après expiration) : $3,75/MTok, soit +25 % — amorti dès le deuxième appel dans la fenêtre de 5 minutes
• Seuil minimum à respecter : 1 024 tokens pour Sonnet, 2 048 tokens pour Haiku

Sur un assistant qui traite 1 000 questions par jour avec un contexte stable de 5 000 tokens, le gain mensuel dépasse facilement 400 $ sur Claude 3.5 Sonnet. Sans la moindre modification de logique métier.

Activer le cache : un header et un champ JSON

Il n'y a rien à refactorer. Le prompt caching s'active avec le header anthropic-beta: prompt-caching-2024-07-31 et un champ cache_control placé sur le bloc à mettre en cache. Le point de rupture (cache breakpoint) se positionne à la fin du contenu stable — typiquement ton prompt système. Voici une intégration complète avec le HttpClient de Symfony 7.1 :

<?php

declare(strict_types=1);

namespace App\Service;

use Symfony\Contracts\HttpClient\HttpClientInterface;

final class ClaudeAnalyzer
{
    private const API_URL = 'https://api.anthropic.com/v1/messages';
    private const MODEL   = 'claude-3-5-sonnet-20240620';

    public function __construct(
        private readonly HttpClientInterface $httpClient,
        private readonly string $anthropicApiKey,
    ) {}

    public function analyze(string $userQuery): string
    {
        // Contenu stable : chargé une fois, caché 5 min côté API Anthropic
        $systemPrompt = $this->loadKnowledgeBase();

        $response = $this->httpClient->request('POST', self::API_URL, [
            'headers' => [
                'x-api-key'         => $this->anthropicApiKey,
                'anthropic-version' => '2023-06-01',
                'anthropic-beta'    => 'prompt-caching-2024-07-31',
            ],
            'json' => [
                'model'      => self::MODEL,
                'max_tokens' => 1024,
                'system'     => [
                    [
                        'type'          => 'text',
                        'text'          => $systemPrompt,
                        'cache_control' => ['type' => 'ephemeral'], // <- le cache breakpoint
                    ],
                ],
                'messages' => [
                    ['role' => 'user', 'content' => $userQuery],
                ],
            ],
        ]);

        $data = $response->toArray();

        return $data['content'][0]['text'];
    }

    private function loadKnowledgeBase(): string
    {
        // 5 000+ tokens : docs produit, règles métier, FAQ…
        // Le contenu DOIT être identique entre les appels pour déclencher un cache hit
        return file_get_contents(__DIR__ . '/../../resources/prompts/knowledge-base.txt');
    }
}

Lire les métriques de cache dans la réponse

L'API retourne dans usage quatre compteurs distincts. Surveille-les pour valider que le cache est bien actif et mesurer le retour sur investissement réel :

{
  "usage": {
    "input_tokens": 38,
    "cache_creation_input_tokens": 5021,
    "cache_read_input_tokens": 0,
    "output_tokens": 312
  }
}

Au premier appel, cache_creation_input_tokens est non nul : tu paies le write premium (+25 %). Dès le deuxième appel dans la fenêtre de 5 minutes, c'est cache_read_input_tokens qui prend la valeur et le coût s'effondre. Si ce compteur reste à zéro sur les appels suivants, ton prompt système varie entre les requêtes — un timestamp, un UUID ou un identifiant utilisateur injecté accidentellement suffit à invalider le cache.

Quand le prompt caching vaut vraiment le déploiement

• Assistants documentaires : FAQ produit, base de connaissance, manuels techniques — le contexte est identique à chaque question utilisateur
• Pipelines de traitement en lot : classifier 500 e-mails avec les mêmes instructions, la latence chute de 85 % dès le deuxième item
• Support client automatisé : les règles métier et le script de réponse ne varient pas entre deux tickets consécutifs
• Analyse de code assistée : les conventions du projet en system prompt, seul le diff change à chaque appel
• À éviter si le prompt système est généré dynamiquement par utilisateur ou contient des données personnalisées — aucun cache hit possible, tu paies le write premium pour rien

Ce qu'il faut retenir pour l'intégrer dès maintenant

• Ajoute le header anthropic-beta: prompt-caching-2024-07-31 à toutes tes requêtes concernées
• Place cache_control: {type: ephemeral} à la fin de chaque bloc stable (system prompt, documents de référence)
• Garde ton prompt système dans un fichier versionné — toute modification invalide le cache immédiatement
• Monitore cache_read_input_tokens dans tes logs pour confirmer les hits et calculer les économies réelles
• La beta est disponible sans liste d'attente : il suffit d'opter via le header

Le prompt caching est l'une des optimisations LLM les plus rentables disponibles aujourd'hui : zéro refactoring d'architecture, un header HTTP supplémentaire, et des coûts divisés par dix sur les cas d'usage à contexte stable. Si tu veux auditer tes intégrations API existantes pour identifier les gains rapides — prompt caching, sélection de modèle, batching — le Bear Scan est fait pour ça : un audit technique ciblé livré en une semaine, avec un plan d'action chiffré.