Claude 3 Sonnet et Claude 2 retirés — migration express vers Sonnet 4

Ce matin, tu as peut-être découvert des model_not_found dans tes logs. Depuis le 21 juillet 2025, Anthropic a définitivement retiré trois modèles de son API publique : Claude 3 Sonnet (claude-3-sonnet-20240229), Claude 2 (claude-2.0) et Claude 2.1 (claude-2.1). Tout appel vers ces identifiants retourne désormais une erreur, quel que soit le plan ou la région. La dépréciation avait été annoncée six mois à l'avance, le 21 janvier 2025, sur platform.anthropic.com. Mais en production, c'est souvent le lendemain matin qu'on le découvre. Ce guide donne les étapes concrètes pour migrer en moins d'une heure.

Trois modèles retirés, une seule cible

Le remplaçant direct pour les trois modèles est Claude Sonnet 4, disponible sous l'identifiant claude-sonnet-4-20250514 depuis le 22 mai 2025. L'impact sur ta facture varie selon le modèle d'origine — voici la comparaison qui compte avant de mesurer l'effet budgétaire de la migration.

• claude-2.0 — 100 K tokens de contexte, ~8 $ input / 24 $ output par MTok → claude-sonnet-4-20250514 : contexte 200 K, ~3 $ / 15 $ par MTok. Baisse de coût et doublement du contexte.
• claude-2.1 — 200 K tokens de contexte, ~8 $ input / 24 $ output par MTok → claude-sonnet-4-20250514 : même fenêtre de contexte, tarif divisé par 2,5. Migration rentable immédiatement.
• claude-3-sonnet-20240229 — 200 K tokens de contexte, ~3 $ / 15 $ par MTok → claude-sonnet-4-20250514 : tarif identique, qualité de génération nettement supérieure.

<?php
// Avant — erreur depuis le 21 juillet 2025
$response = $client->messages()->create([
    'model'     => 'claude-3-sonnet-20240229', // ou 'claude-2.1' / 'claude-2.0'
    'maxTokens' => 1024,
    'messages'  => [['role' => 'user', 'content' => $prompt]],
]);

// Après — Claude Sonnet 4
$response = $client->messages()->create([
    'model'     => 'claude-sonnet-4-20250514',
    'maxTokens' => 1024,
    'messages'  => [['role' => 'user', 'content' => $prompt]],
]);

// Conseil : centralise la référence en constante ou variable d'env
// ANTHROPIC_MODEL=claude-sonnet-4-20250514 dans ton .env

Deux paramètres API qui bloquent la migration

Pour la grande majorité des intégrations, changer l'identifiant de modèle suffit. Deux patterns courants génèrent néanmoins un 400 invalid_request_error sur la famille Claude 4 et doivent être corrigés avant tout déploiement en production.

• Prefill assistant supprimé. Terminer le tableau messages par un tour role: "assistant" pour forcer un format de sortie (JSON, XML, CSV…) n'est plus supporté dans la famille Claude 4. L'API retourne immédiatement un 400. Solution recommandée : outputConfig avec un json_schema, ou une instruction système explicite.
• output_format remplacé par outputConfig. Le paramètre top-level output_format (déjà déprécié depuis plusieurs versions) est définitivement fermé. Migre vers outputConfig: ['format' => [...]] tel que montré ci-dessous.

<?php
// Pattern à supprimer — retourne 400 sur Claude Sonnet 4
$messages = [
    ['role' => 'user',      'content' => 'Extrais le prénom dans ce texte : Alice Dupont.'],
    ['role' => 'assistant', 'content' => '{"prenom": "'],  // ← prefill supprimé
];

// Remplacement : JSON schema via outputConfig
$response = $client->messages()->create([
    'model'        => 'claude-sonnet-4-20250514',
    'maxTokens'    => 256,
    'outputConfig' => [
        'format' => [
            'type'                 => 'json_schema',
            'schema'               => [
                'type'                 => 'object',
                'properties'           => ['prenom' => ['type' => 'string']],
                'required'             => ['prenom'],
                'additionalProperties' => false,
            ],
        ],
    ],
    'messages' => [
        ['role' => 'user', 'content' => 'Extrais le prénom dans ce texte : Alice Dupont.'],
    ],
]);

Prompt caching : neutraliser la facture sur les appels répétés

À fort volume — traitement de documents, chatbot en production, pipeline RAG — le prompt caching réduit drastiquement le coût des appels répétitifs. Le principe : tu annotes les blocs stables du prompt (instructions système, exemples few-shot, référentiel métier) avec une directive cache_control. Lors des appels suivants, ces tokens sont lus depuis le cache et facturés à environ 10 % du tarif input normal. La première écriture en cache coûte ~125 % du tarif de base, mais elle est amortie dès le deuxième appel identique.

<?php
$systemPrompt = file_get_contents(__DIR__ . '/prompts/extraction-system.txt');
// Le fichier doit faire au minimum 1 024 tokens pour que le cache s'active

$response = $client->messages()->create([
    'model'     => 'claude-sonnet-4-20250514',
    'maxTokens' => 2048,
    'system'    => [
        [
            'type'          => 'text',
            'text'          => $systemPrompt,        // ← partie stable
            'cache_control' => ['type' => 'ephemeral'],
        ],
    ],
    'messages' => [
        ['role' => 'user', 'content' => $documentToProcess], // ← partie variable
    ],
]);

// Inspecter les métriques de cache dans la réponse
$usage = $response->usage;
// $usage->cacheCreationInputTokens → tokens écrits en cache (~1.25× tarif, une seule fois)
// $usage->cacheReadInputTokens     → tokens lus depuis le cache (~0.10× tarif)

Un seuil à ne pas sous-estimer : le bloc à mettre en cache doit atteindre au minimum 1 024 tokens sur Claude Sonnet 4. En dessous de ce seuil, Anthropic ignore silencieusement la directive cache_control sans renvoyer d'erreur — le cache ne s'active tout simplement pas. Vérifie la taille de ton prompt système avec l'endpoint count_tokens avant de déployer, ou consulte le champ cacheCreationInputTokens dans la réponse : s'il est à zéro, ton prompt est trop court.

Tu as des intégrations Claude en production — API de traitement, pipeline Symfony, chatbot B2B — et tu veux t'assurer que la migration est propre : modèles, paramètres API, stratégie de cache, sans régression ni surprise budgétaire ? Bear Upgrade accompagne les équipes PHP et Symfony sur ces chantiers de migration : audit de l'existant, plan de migration et mise en production supervisée.